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ABOUT THIS CHAPTER 


This chapter describes the Menu Manager, the part of the Toolbox that allows you 
to create sets of menus, and allows the user to choose from the commands in 
those menus. 


You should already be familiar with: 


* resources, as described in the Resource Manager chapter 

¢ the basic concepts and structures behind QuickDraw, particularly 
points, rectangles, and character style 

« the Toolbox Event Manager 
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ABOUT THE MENU MANAGER 


The Menu Manager supports the use of menus, an integral part of the Macintosh 
user interface. Menus allow users to examine all choices available to them at 
any time without being forced to choose one of them, and without having to 
remember command words or special keys. The Macintosh user simply positions the 
cursor in the menu bar and presses the mouse button over a menu title. The 
application then calls the Menu Manager, which highlights that title (by 
inverting it) and "pulls down" the menu below it. As long as the mouse button is 
held down, the menu is displayed. Dragging through the menu causes each of the 
menu items (commands) in it to be highlighted in turn. If the mouse button is 
released over an item, that item is "chosen". The item blinks briefly to confirm 
the choice, and the menu disappears. 


When the user chooses an item, the Menu Manager tells the application which item 
was chosen, and the application performs the corresponding action. When the 
application completes the action, it removes the highlighting from the menu 
title, indicating to the user that the operation is complete. 


If the user moves the cursor out of the menu with the mouse button held down, 
the menu remains visible, though no menu items are highlighted. If the mouse 
button is released outside the menu, no choice is made: The menu just 
disappears and the application takes no action. The user can always look at a 
menu without causing any changes in the document or on the screen. 


For the 128K ROM, the Menu Manager includes the following enhancements: 


¢ The AddResMenu and InsertResMenu procedures have been modified to work 
with the font family resource type ('FOND'). If you call either routine 
for a resource of type 'FONT', they first add all instances of type 'FOND' 
and then all instances of type 'FONT'. The Menu Manager ignores resources 
of type 'NFNT'. Both routines, before adding a new item to the menu, first 
check to see that an item with the same name is not already in the menu. 
If an item with the same name is already there, the new item is not added. 
This prevents duplication and gives items of type 'FOND' precedence over 
items of type 'FONT'. 

e AddResMenu and InsertResMenu both sort the items alphabetically as they're 
placed in the menu; the order of items already in the menu, however, is 
unaffected. Neither routine enables the items. 

¢ Two routines, InsMenuItem and DelMenuItem, let you insert and delete 
individual items from an existing menu. Use of these routines is 
discouraged except in certain situations where the user expects a menu 
to change (such as list of open windows). 


This chapter also describes the enhancements to the Menu Manager for the 
Macintosh II. All changes are backward-compatible with the Macintosh Plus and 
the Macintosh SE, so your existing programs using Menu Manager routines will 
continue to work and produce the same screen display as before. All new 
features, except for color menus, will work on the Macintosh Plus and Macintosh 
SE using System 4.1 and later. 
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To best use the material presented in this chapter, you should be familiar with 
QuickDraw, and should also know how to use resources in your application 
programs. 


For the Macintosh Plus, Macintosh SE, and Macintosh II, the new Menu Manager 
provides these features: 


e Menus can include submenus. This feature is known as hierarchical menus. 
Hierarchical menu items have a small filled black triangle pointing to 
the right, indicating that a submenu exists. 

e Pop-up menus are supported. 

e Scrolling menus are marked with a filled black triangle indicator at 
the top or bottom of the menu, to indicate which direction the menu 
may scroll. 

e Within menus, font names for international scripts are printed in the 
actual script rather than in the system font when the Script Manager 
is installed. 

¢ A new definition procedure (defproc), called the Menu Bar Defproc, 
handles such functions as drawing the menu bar and saving and restoring 
bits behind a menu. 

e It is now possible to determine if a user has chosen a disabled menu item. 


For the Macintosh II, the new Menu Manager provides these features: 


e Color can be added to menus. When the menu title is the appleMark, a 
color apple is displayed instead of the system font appleMark. 
Applications may provide additional colors in menus if desired. 


A bug in the DrawMenuBar procedure has been fixed; formerly, DrawMenuBar would 
redraw incorrectly when a menu was highlighted. If your application called 
HiliteMenu or FlashMenuBar to correct this, the result will now be 
overcompensation, and the menu title will be unhighlighted. Another change 
overcomes a Limitation in the original menu data structure; the EnableItem and 
DisableItem routines now refer to the menu title and the first 31 items only, 
and all items beyond 31 are always enabled. 


The Menu Bar 


The menu bar always appears at the top of the Macintosh screen; nothing but the 
cursor ever appears in front of it. The menu bar is white, 20 pixels high, and 
as wide as the screen, with a 1-pixel black lower border. The menu titles in it 
are always in the system font and the system font size (see Figure 1). 


In applications that support desk accessories, the first menu should be the 
standard Apple menu (the menu whose title is an apple symbol). The Apple menu 
contains the names of all available desk accessories. When the user chooses a 
desk accessory from the menu, the title of a menu belonging to the desk 
accessory may appear in the menu bar, for as long as the accessory is active, or 
the entire menu bar may be replaced by menus belonging to the desk accessory. 
(Desk accessories are discussed in detail in the Desk Manager chapter. ) 
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Figure 1—The Menu Bar 


Figure 1—The Menu Bar 


A menu may be temporarily disabled, so that none of the items in it can be 
chosen. A disabled menu can still be pulled down, but its title and all the 
items in it are dimmed. 


The maximum number of menu titles in the menu bar is 16; however, ten to twelve 
titles are usually all that will fit, and you must leave at least enough room in 
the menu bar for one desk accessory menu. Also keep in mind that if your program 
is likely to be translated into other languages, the menu titles may take up 
more space. If you're having trouble fitting your menus into the menu bar, you 
should review your menu organization and menu titles. 


Appearance of Menus 


A standard menu consists of a number of menu items listed vertically inside a 
shadowed rectangle. A menu item may be the text of a command, or just a line 
dividing groups of choices (see Figure 2). An ellipsis (...) following the text 
of an item indicates that selecting the item will bring up a dialog box to get 
further information before the command is executed. Menus always appear in front 
of everything else (except the cursor); in Figure 2, the menu appears in front 
of a document window already on the screen. 


Note: In the 64K ROM version of the Menu Manager, if the user attempted to 
pull down an empty menu (one with no items), an unsightly empty menu 
of arbitrary size was displayed. In the 128K ROM version, the menu 
title is highlighted but the menu is not pulled down at all. 
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Figure 2—A Standard Menu 


The text of a menu item always appears in the system font and the system font 
Size. Each item can have a few visual variations from the standard appearance: 


e An icon to the left of the item's text, to give a symbolic representation 
of the item's meaning or effect. 

e A check mark or other character to the left of the item's text (or icon, 
if any), to denote the status of the item or of the mode it controls. 

¢ The Command key symbol and another character to the right of the item's 
text, to show that the item may be invoked from the keyboard (that is, 
it has a keyboard equivalent). Pressing this key while holding down the 
Command key invokes the item just as if it had been chosen from the menu 
(see "Keyboard Equivalents for Commands" below). 

e A character style other than the standard, such as bold, italic, 
underline, or a combination of these. (The QuickDraw chapter gives a 
full discussion of character style.) 

e A dimmed appearance, to indicate that the item is disabled, and can't 
be chosen. The Cut, Copy, and Clear commands in Figure 2 are disabled; 
dividing lines are always disabled. 


Note: Special symbols or icons may have an unusual appearance when dimmed; 
notice the dimmed Command symbol in the Cut and Copy menu items in 
Figure 2. 


If the standard menu doesn't suit your needs—for example, if you want more 
graphics, or perhaps a nonlinear text arrangement—you can define a custom menu 
that, although visibly different to the user, responds to your application's 
Menu Manager calls just like a standard menu. 


Hierarchical Menus 
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A hierarchical menu is a menu that includes, among its various menu choices, the 
ability to display a submenu. In most cases the submenu appears to the right of 
the menu item used to select it, and is marked with a filled triangle indicator. 
Throughout this chapter, there is a distinction made between a menu and a 
hierarchical menu. If the word hierarchical is not used, then the reference is 
to a nonhierarchical menu. At times, though, the term normal or regular menu 
may appear when referring to a nonhierarchical menu. The term submenu is used to 
describe any menu that is the "offspring" of a previous menu. 


Several illustrations of hierarchical menus appear in the Macintosh User 
Interface Guidelines chapter, with recommendations for their use. 


Pop-Up Menus 


The PopUpMenuSelect routine allows an application to create a pop-up menu. A 
pop-up menu is one that isn't in the menu bar, but appears somewhere else on the 
screen (usually in a dialog box) when the user presses in a particular place. A 
pop-up menu may be colored like any other menu, and it may have submenus. Pop-up 
menus are typically used for lists of items, for example, a list of fonts. See 
the Macintosh User Interface Guidelines chapter for a more complete description 
of how to use pop-up menus in your application. 


Color Menus 


For the Macintosh II, color can be added to menus in video modes with a 
resolution of two bits or greater. Your application can specify the menu bar 
color, menu title colors, the background color of a pulled down menu, and a 
separate color for each menu item's mark, name, and command character. As the 
Macintosh II is shipped, the only user observable menu color is the color Apple 
symbol, which appears in the 4-bit and 8-bit modes. If the menu title is the 
appleMark (a one-character string containing the appleMark character $14) the 
color Apple symbol appears instead of the system font appleMark. 


Multicolor menus should be used with discretion: user testing has shown that the 
use of many arbitrary colors can cause user confusion and slow down menu item 
recognition. See the Macintosh User Interface Guidelines chapter for more 
information on using color in applications. 


The user can specify system-wide menu colors along with a colored desktop 
pattern with the Control Panel, and applications should avoid overriding the 
user choices. The system-wide menu colors are specified in the 'mctb' 
resource = @ in the System file, and include 


the menu bar color 

a default color for menu titles 

a default color for the background of a pulled-down menu 
a default color for menu items. 


eoeee 


The user-specified default colors may be overridden by a separate 'mctb' 
resource = @ in the application's resource file. 
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Of course, a user can also use a resource editor to completely color an 
application's menus by adding or changing its 'mctb' resource(s). If your 
application doesn't need color menus, it should not try to override the user's 
default color choices. However, if the application needs specific colors that 
might clash with a user's default choices, the user should be prompted for an 
alternate choice of colors. An application should only override a user's choices 
as a last resort; let the user's color preferences prevail. 


Keyboard Equivalents for Commands 


Your program can set up a keyboard equivalent for any of its menu commands so 
the command can be invoked from the keyboard with the Command key. The character 
you specify for a keyboard equivalent will usually be a letter. The user can 
type the letter in either uppercase or lowercase. For example, typing either "C" 
or "c" while holding down the Command key invokes the command whose equivalent 
is. "G". 


Note: For consistency between applications, you should specify the letter 
in uppercase in the menu. 


You can specify characters other than letters for keyboard equivalents. However, 
the Shift key will be ignored when the equivalent is typed, so you shouldn't 
specify shifted characters. For example, when the user types Command-+, the 
system reads it as Command-=. 


Command-Shift-number combinations are not keyboard equivalents. They're detected 
and handled by the Toolbox Event Manager function GetNextEvent, and are never 
returned to your program. (This is how disk ejection with Command-Shift-1 or 2 
is implemented.) Although it's possible to use unshifted Command-number 
combinations as keyboard equivalents, you shouldn't do so, to avoid confusion. 


Warning: You must use the standard keyboard equivalents Z, X, C, and V for 
the editing commands Undo, Cut, Copy, and Paste, or editing won't 
work correctly in desk accessories. 
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MENUS AND RESOURCES 


The general appearance and behavior of a menu is determined by a routine called 
its menu definition procedure, which is stored as a resource in a resource file. 
The menu definition procedure performs all actions that differ from one menu 
type to another, such as drawing the menu. The Menu Manager calls the menu 
definition procedure whenever it needs to perform one of these basic actions, 
passing it a message that tells which action to perform. 


The standard menu definition procedure is part of the system resource file. It 
lists the menu items vertically, and each item may have an icon, a check mark or 
other symbol, a keyboard equivalent, a different character style, or a dimmed 
appearance. If you want to define your own, nonstandard menu types, 

you'll have to write menu definition procedures for them, as described later in 
the section "Defining Your Own Menus". 


You can also use a resource file to store the contents of your application's 
menus. This allows the menus to be edited or translated to another language 
without affecting the application's source code. The Menu Manager lets you read 
complete menu bars as well as individual menus from a resource file. 


Warning: Menu resources should never be marked as purgeable. If a Menu 
Manager routine tries to access a menu that's been purged, a 
system error (ID 84) will occur. 


Even if you don't store entire menus in resource files, it's a good idea to 
store the text strings they contain as resources; you can call the Resource 
Manager directly to read them in. Icons in menus are read from resource files; 
the Menu Manager calls the Resource Manager to read in the icons. 


There's a Menu Manager procedure that scans all open resource files for 
resources of a given type and installs the names of all available resources of 
that type into a given menu. This is how you fill a menu with the names of all 
available desk accessories or fonts, for example. 


Note: If you use a menu of this type, check to make sure that at least one 
item is in the menu; if not, you should put a disabled item in it that 
says "None" (or something else indicating the menu is empty). 
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MENU MANAGER DATA STRUCTURES 


The Menu Manager keeps all the information it needs for its operations on a 
particular menu in a menu record. The menu record contains the following: 


¢ The menu ID, a number that identifies the menu. The menu ID can be the 
same number as the menu's resource ID, though it doesn't have to be. 

¢ The menu title. 

¢ The contents of the menu-the text and other parts of each item. 

¢ The horizontal and vertical dimensions of the menu, in pixels. The menu 
items appear inside the rectangle formed by these dimensions; the black 
border and shadow of the menu appear outside that rectangle. 

¢ A handle to the menu definition procedure. 

e Flags telling whether each menu item is enabled or disabled, and whether 
the menu itself is enabled or disabled. 


The data type for a menu record is called MenuInfo. A menu record is referred to 
by a handle: 


TYPE MenuPtr 
MenuHandle 


“MenulInfo; 
“MenuPtr; 


You can store into and access all the necessary fields of a menu record with 
Menu Manager routines, so normally you don't have to know the exact field names. 
However, if you want more information about the exact structure of a menu 
record—if you're defining your own menu types, for instance—-it's given below. 


The MenuInfo Data Type 
The type MenuInfo is defined as follows: 


TYPE MenuInfo = RECORD 


menuID: INTEGER; {menu ID} 
menuWidth: INTEGER; {menu width in pixels} 
menuHeight : INTEGER; {menu height in pixels} 
menuProc: Handle; {menu definition procedure} 
enableFlags: LONGINT; {tells if menu or items are enabled} 
menuData: Str255 {menu title (and other data) } 

END; 


The menuID field contains the menu ID. MenuWidth and menuHeight are the menu's 
horizontal and vertical dimensions in pixels. MenuProc is a handle to the menu 
definition procedure for this type of menu. 


Bit 0 of the enableFlags field is 1 if the menu is enabled, or 0 if it's 
disabled. Bits 1 to 31 similarly tell whether each item in the menu is enabled 
or disabled. 
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The menuData field contains the menu title followed by variable-length data that 
defines the text and other parts of the menu items. The Str255 data type enables 
you to access the title from Pascal; there's actually additional data beyond the 
title that's inaccessible from Pascal and is not reflected in the MenuInfo data 

structure. 


Warning: You can read the menu title directly from the menuData field, but 
do not change the title directly, or the data defining the menu 
items may be destroyed. 


Menu Lists 


A menu list contains handles to one or more menus, along with information about 
the position of each menu in the menu bar. The current menu list contains 
handles to all the menus currently in the menu bar; the menu bar shows the 
titles, in order, of all menus in the menu list. When you initialize the Menu 
Manager, it allocates space for the maximum-size menu list. 


The Menu Manager provides all the necessary routines for manipulating the 
current menu list, so there's no need to access it directly yourself. As a 
general rule, routines that deal specifically with menus in the menu list use 
the menu ID to refer to menus; those that deal with any menus, whether in the 
menu list or not, use the menu handle to refer to menus. Some routines refer to 
the menu list as a whole, with a handle. 


Assembly-language note: The global variable MenuList contains a handle to 
the current menu list. The menu list has the format 
shown below. 


Number of bytes Contents 
2 bytes Offset from beginning of menu list 


to last menu handle (the number of 
menus in the list times 6) 


2 bytes Horizontal coordinate of right edge 
of menu title of last menu in list 
2 bytes Not used 


For each menu: 


4 bytes Menu handle 
2 bytes Horizontal coordinate of left edge 
of menu 


For backward compatibility, the MenuInfo structure has not been changed, 
although several of its fields have new meanings for hierarchical menus. The 
MenuList has also kept its general structure to provide backward compatibility, 
and still contains six bytes of header information and six bytes of information 
for each menu; however, each menu entry is now allocated dynamically. There is 
also additional storage at the end of the MenuList for hierarchical and pop-up 
menus. 
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Except where explicitly noted, the data structures in the following section are 
listed for information only; applications should never interrogate or change 
them directly. The Menu Manager routines provide all needed functions. 


Data Structures for Hierarchical Menus 


A new MenuList data structure accommodates hierarchical menus. It dynamically 
allocates storage space as menus and hierarchical menus are added and deleted. 


Warning: The MenuList data structure is listed for information only; 
applications should never access it directly. 


The following TYPE definition is for conceptual purposes only; there is no such 
data structure in the Menu Manager: 


TYPE InitialMenuList = RECORD 


LlastMenu: INTEGER; {offset} 
lastRight: INTEGER; {pixels} 
mbResID: INTEGER; {upper 13 bits used as } 


{ mbarproc resource ID } 
{ low 3 bits used as } 
{ mbVariant } 

LastHMenu: INTEGER; {offset} 

menuTitleSave: pixMapHandle {handle to bits behind} 
{ inverted menu title} 


END; 
Field descriptions 
lastMenu The lLastMenu field contains the offset to the last regular 
menu in the MenuList. 
lastRight The lastRight field contains the pixel location of the right 
edge of the rightmost menu in the menu bar. 
mbResID The mbResID field stores the resource ID of the menu bar defproc 


used by the application. Its default value is zero. The upper 13 
bits are used as the resource ID. The low three bits are passed 
to the menu bar defproc ('MBDF') as the mbVariant. 

LastHMenu The lLastHMenu field contains the offset to the last 
hierarchical menu in the MenuList. 

menuTitleSave The menuTitleSave field stores a PixMapHandle to the saved 
"bits behind" the selected menu title. 


When the MenuList data structure is initialized, there is no space allocated for 
menu handles or hierarchical menu handles. When a menu is allocated, six bytes 
are inserted between the mbResID and lastHMenu fields. As each menu is allocated 
or deleted, the space between mbResID and lastHMenu grows or shrinks 
accordingly. Space is allocated for hierarchical menus after the MenuTitleSave 
field, and its space is also dynamic. 


A sample MenuList Data Structure with X menus and Y hierarchical menus appears 
below. 


Warning: The sample MenuList structure is not a valid Pascal type because 
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of its dynamic size; it's shown for conceptual purposes only. 


TYPE MenuRec = RECORD 
menuOH: Menuhandle; 
menuLeft: INTEGER; 
END; 
HMenuRec = RECORD 
menuHOH: Menuhandle; 
reserved: INTEGER; 
END; 
DynamicMenuList = RECORD 
LlastMenu: 
lastRight: 
mbResID: 
menu: 
LastHMenu: 
menuTitleSave: 
hMenu: 


END; 


{menu's data} 
{pixels} 


{hierarchical menu's data} 
{reserved for future use} 


INTEGER; {offset} 
INTEGER; {pixels} 
INTEGER; 


ARRAY [1..X] OF MenuRec; 
{X is the number of menus} 
INTEGER; {offset} 
PixMapHandle {handle to bits behind } 
{ inverted menu title} 


ARRAY [1..Y] OF HMenuRec; 


{Y is the number of } 
{ submenus used} 


The initial MenuList data structure is allocated by InitMenus each time an 
application is started. Any subsequent calls to InitMenus, while the application 
is running, don't cause the MenuList data structure to be reallocated.The 
MenuInfo data structure is shown below; this version is similar to what is shown 


earlier in this section, 


Warning: 


but includes additional information about menu items. 


The MenuInfo data structure is listed for information only; 


applications should never access it directly. This structure is 
not a valid Pascal type because of its dynamic size; it's shown 


for conceptual purposes only. 


TYPE MenuInfo = RECORD 


menulID: INTEGER; {menu ID} 
menuWidth: INTEGER; {pixels} 
menuHeight : INTEGER; {pixels} 
menuProc: Handle; {handle} 
enableFlags: LONGINT; {bit string} 
menuTitle: String; {menu title name} 
itemData: ARRAY [1..X] OF 
itemString: string; {item name} 
itemIcon: BYTE; {iconnum- 256} 
itemCmd: char; {item cmd key} 
itemMark: char; {item mark is a byte} 
{ value for } 
{ hierachical menus} 
itemStyle: Style; {bit string} 
endMarker: Byte; {zero-length string } 


{ indicates no more } 
{ menu items} 
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END; 


Field descriptions 


menuID The menuID field contains the menu ID of the menu. 

menuWidth The menuWidth field contains the width in pixels of the menu. 

menuHeight The menuHeight field contains the height in pixels of the menu. 

menuProc The menuProc field contains a handle to the menu's definition 
procedure. 


enableFlags The enableFlags field is a bit string which allows the menu and 
the first 31 items to be enabled or disabled. All items beyond 
31 are always enabled. 

menuTitle The menuTitle field is a string containing the menu title. 

itemData The itemData field is an array containing the following 
information for each menu item: item name, item icon number, 
item command key equivalent, item mark, and item style. For 
hierarchical menus, the itemMark field is a byte value. 

endMarker The endMarker field is a byte value, which contains zero if 
there are no more menu items. 


The contents of the itemData array are the same for hierarchical and 
nonhierarchical menus, but for hierarchical menus the itemMark field is a byte 
value, which Limits hierarchical menu menuID values to between 0 and 255. 
Hierarchical menus numbered 236 to 255 are reserved for use by desk accessories. 
Desk accessories must remove their hierarchical menus from the MenuList each 
time their window is not the frontmost, to prevent hierarchical menu collisions 
with other desk accessories. 


Color Menu Data Structures 


For the Macintosh II, menus can be colored in 2-bit mode or higher, in both 
color and gray-scale. The menu color information is contained in a table format, 
but because this format is different from the standard color table format, it is 
referred to as the menu color information table, rather than the menu color 
table. A menu color information table is composed of several entries, each of 
which is an MCEntry record. These data structures are shown below: 


TYPE MCEntryPtr = “MCEntry; 
MCEntry = RECORD 
mctID: INTEGER; {menu ID. ID = 0 is } 
{ the menu bar} 
mctiItem: INTEGER; {menu entry. Item = 0 } 
{ is a title} 
mctRGB1: RGBColor; {usage depends on ID and Item} 
mctRGB2: RGBColor; {usage depends on ID and Item} 
mctRGB3: RGBColor; {usage depends on ID and Item} 
mctRGB4: RGBColor; {usage depends on ID and Item} 
mctReserved: INTEGER; {reserved for internal use} 
END; 
MCTable = ARRAY [0..0] of MCEntry; {The menu entries are } 
{ represented in this array} 
MCTablePtr = “MCTable; 
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MCTableHandle = *“MCTablePtr; 


Field descriptions 


mctID The mctID field contains the menu ID of the menu. A value of 
mctID = 0 means that this is the menu bar. 

mctItem The mctItem field contains the menu item. A value of item = 0 
means that the item is a menu title. 

mctRGB1 The mctRGB1 field contains a color value which depends on the 
mctID and mctItem. See the description in the following section. 

mctRGB2 The mctRGB2 field contains a color value which depends on the 
mctID and mctItem. See the description in the following section. 

mctRGB3 The mctRGB3 field contains a color value which depends on the 
mctID and mctItem. See the description in the following section. 

mctRGB4 The mctRGB4 field contains a color value which depends on the 


mctID and mctItem. See the description in the following section. 
mctReserved The mctReserved field is used internally; applications must not 
use this field. 


The color information table is created at InitMenus time, and its handle is 
stored in the global variable MenuCInfo ($D50). Like the MenuList data 
structure, it is only created the first time InitMenus or InitProcMenu is called 
for an application. 


A menu color information table is shown in Figure 3. 
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Figure 3—Menu Color Information Table 


Figure 3—Menu Color Information Table 


There is always at least one entry in the color table, the last entry, which has 
the arbitrary value —99 in the ID field as an "end-of-table" marker. (This means 
that the value —99 cannot be used as an ID by an application.) Note that the 
other fields in the "end-of-table" entry are reserved by use for Apple. Each 
entry in the color information table has seven fields. 
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The first two fields define the entry's menu and item. The last field is used 
internally and has no information for use by programmers. The other fields 
define colors depending on what type of menu element the entry describes. All 
colors are specified as RGB colors. There are three types of entries in the menu 
color information table: one type for the menu bar, one type for menu titles, 
and one type for menu items. 


The menu bar entry has ID = 0, Item = 0. There will be at most one menu bar 
entry in the color information table. If there is no menu bar entry, the default 
menu bar colors are black text on a white background. The fields in a menu bar 
entry are as follows: 


* mctRGB1l is the default color for menu titles. If a menu title doesn't 
have an entry in the table, then this is the color used to draw the title. 

¢ mctRGB2 is the default color for the background of a pulled down menu. 
If a menu title doesn't have an entry in the table, this color is used 
as the menu's background color. 

* mctRGB3 is the default color for the items in a pulled down menu. If a 
menu item doesn't have an entry ina table, and if the title for that 
menu item doesn't also have an entry, this color will be used to color 
the mark, name, and Command-key equivalent of the item. 

* mctRGB4 is the menu bar color. 


The menu title entry has ID <> 0, Item = Q. There will be at most one title 
entry for each menu in the color information table. If there is no title entry, 
the title, menu background, and menu items are drawn using the defaults found in 
the menu bar entry. If there is no menu bar entry, the default colors are black 
on white. The fields in a title entry areas follows: 


¢ mctRGBG1 is the title color. 

¢ mctRGB2 is the menu bar color. This is duplicated here from the menu bar 
entry to speed menu drawing. 

e mctRGB3 is the default color for the menu items. If a menu item doesn't 
have an entry in the table, this color will be used to color the mark, 
name, and Command-key equivalent of the item. 

e mctRGB4 is the menu's background color. 


The menu item entry has ID <> 0, Item <> Q. There will be at most one item entry 
for each menu item in the color information table. If there is no entry for a 
particular item, the item mark, name, and Command-key equivalent are drawn using 
the defaults found in the title entry. If there is no title entry, the 
information in the menu bar entry is used. If there is no menu bar entry, the 
mark, name, and Command-key equivalent are drawn in black. The fields in an item 
entry are as follows: 


mctRGB1 is the mark color. 

mctRGB2 is the name color. 

mctRGB3 is the Command-key equivalent. 

mctRGB4 is the menu's background color. It's duplicated here to 
speed menu drawing. 


eoeee 


It's not possible to specify an icon's color. Black and white icons are drawn in 
the item's name color. Icons may be colored using a 'cicn' resource instead of 
an 'ICON' resource. When an icon is drawn in a menu, the menu defproc attempts 
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to load the 'cicn' resource first, and if it isn't found, searches for the 
'ICON' resource. See the QuickDraw chapter for more information on color icons. 


Menu Color Information Table Resource Format 


The resource type for a menu color information table is 'mctb'. Once read into 
memory, this data is transferred into the application's menu color information 
table. The resource data format is identical to an MCTable, with the addition of 
a leading word that contains the number of entries in the resource: 


TYPE MenuCRsrc = RECORD 
numEntries: integer; 
data: array [1..numEntries] of MCEntry; 
END; 


The 'mctb' resource is loaded automatically by two routines. InitMenus attempts 
to load an 'mctb' resource = 0, and if it is successful, adds the colors to the 
application's menu color information table. GetMenu attempts to load an 'mctb' 
resource with the same resource ID as the menu it has loaded, and if it 
succeeds, it adds the colors to the application's menu color information table. 
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CREATING A MENU IN YOUR PROGRAM 


The best way to create your application's menus is to set them up as resources 
and read them in from a resource file. If you want your application to create 
the menus itself, though, it must call the NewMenu and AppendMenu routines. 
NewMenu creates a new menu data structure, returning a handle to it. AppendMenu 
takes a string and a handle to a menu and adds the items in the string to the 
end of the menu. 


The string passed to AppendMenu consists mainly of the text of the menu items. 
For a dividing line, use one hyphen (—); AppendMenu ignores any following 
characters, and draws a dotted line across the width of the menu. For a blank 
item, use one or more spaces. Other characters interspersed in the string have 
special meaning to the Menu Manager. These "meta-characters" are used in 
conjunction with text to separate menu items or alter their appearance (for 
example, you can use one to disable any dividing line or blank item). The 
meta-characters aren't displayed in the menu. 


Meta-character Meaning 


or Return Separates items 
Item has an icon 
Item has a check or other mark 
Item has a special character style 
Item has a keyboard equivalent 
Item is disabled 


ANA >t 


None, any, or all of these meta-characters can appear in the AppendMenu string; 
they're described in detail below. To add one text-only item to a menu would 
require a simple string without any meta-characters: 


AppendMenu(thisMenu, 'Just Enough' ) 
An extreme example could use many meta-characters: 

AppendMenu(thisMenu, '(Too Much*1<B/T' ) 
This example adds to the menu an item whose text is "Too Much", which is 
disabled, has icon number 1, is boldfaced, and can be invoked by Command-T. Your 
menu items should be much simpler than this. 
Note: If you want any of the meta-characters to appear in the text of a 


menu item, you can include them by changing the text with the Menu 
Manager procedure SetItem. 


Multiple Items 
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Each call to AppendMenu can add one or many items to the menu. To add multiple 
items in the same call, use a semicolon (;) or a Return character to separate 
the items. The call 


AppendMenu(thisMenu, 'Cut;Copy' ) 
has exactly the same effect as the calls 


AppendMenu(thisMenu, 'Cut' ) 


AppendMenu(thisMenu, 'Copy ) 


Items with Icons 


A circumflex (* ) followed by a digit from 1 to 9 indicates that an icon should 
appear to the left of the text in the menu. The digit, called the icon number, 

yields the resource ID of the icon in the resource file. Icon resource IDs 257 

through 511 are reserved for menu icons; thus the Menu Manager adds 256 to the 

icon number to get the proper resource ID. 


Note: The Menu Manager gets the icon number by subtracting 48 from the ASCII 
code of the character following the "*" (since, for example, the ASCII 
code of "1" is 49). You can actually follow the "*" with any character 
that has an ASCII code greater than 48. 


You can also use the SetItemIcon procedure to install icons in a menu; it 
accepts any icon number from 1 to 255. 


Marked Items 


You can use an exclamation point (!) to cause a check mark or any other 
character to be placed to the left of the text (or icon, if any). Follow the 
exclamation point with the character of your choice; note, however, that 
normally you can't type a check mark from the keyboard. To specify a check mark, 
you need to take special measures: Declare a string variable to have the length 
of the desired AppendMenu string, and assign it that string with a space 
following the exclamation point. Then separately store the check mark in the 
position of the space. 


For example, suppose you want to use AppendMenu to specify a menu item that has 
the text "Word Wraparound" (15 characters) and a check mark to its left. You can 
declare the string variable 

VAR s: STRING[17]; 
and do the following: 

s := '! Word Wraparound'; 


s[2] := CHR(checkMark) ; 
AppendMenu(thisMenu,s) 
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The constant checkMark is defined by the Font Manager as the character code for 
the check mark. 


Note: The Font Manager also defines constants for certain other special 
characters that can't normally be typed from the keyboard: the apple 
symbol, the Command key symbol, and a diamond symbol. These symbols 
can be specified in the same way as the check mark. 


You can call the SetItemMark or CheckItem procedures to change or clear the 
mark, and the GetItemMark procedure to find out what mark, if any, is being 
used. 


Character Style of Items 


The system font is the only font available for menus; however, you can vary the 
character style of menu items for clarity and distinction. The meta-character 
for specifying the character style of an item's text is the less-than symbol 
(<). With AppendMenu, you can assign one and only one of the stylistic 
variations listed below. 


<B Bold 

<I Italic 

<U Underline 
<0 Outline 
<S Shadow 


The SetItemStyle procedure allows you to assign any combination of stylistic 
variations to an item. For a further discussion of character style, see the 
QuickDraw chapter. 


Items with Keyboard Equivalents 


A slash (/) followed by a character associates that character with the item, 
allowing the item to be invoked from the keyboard with the Command key. The 
specified character (preceded by the Command key symbol) appears at the right of 
the item's text in the menu. 


Note: Remember to specify the character in uppercase if it's a letter, and 
not to specify other shifted characters or numbers. 


Given a keyboard equivalent typed by the user, you call the MenuKey function to 
find out which menu item was invoked. 


Disabled Items 


The meta-character that disables an item is the left parenthesis, "(". A 
disabled item cannot be chosen; it appears dimmed in the menu and is not 
highlighted when the cursor moves over it. 
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Menu items that are used to separate groups of items (such as a line or a blank 
item) should always be disabled. For example, the call 


AppendMenu(thisMenu, 'Undo; (-;Cut') 


adds two enabled menu items, Undo and Cut, with a disabled item consisting of a 
line between them. 


You can change the enabled or disabled state of a menu item with the DisableItem 
and EnableItem procedures. 
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USING THE MENU MANAGER 


To use the Menu Manager, you must have previously called InitGraf to initialize 
QuickDraw, InitFonts to initialize the Font Manager, and InitWindows to 
initialize the Window Manager. The first Menu Manager routine to call is the 
initialization procedure InitMenus. 


Your application can set up the menus it needs in any number of ways: 


e Read an entire prepared menu list from a resource file with 
GetNewMBar, and place it in the menu bar with SetMenuBar. 

« Read the menus individually from a resource file using GetMenu, 
and place them in the menu bar using InsertMenu. 

e Allocate the menus with NewMenu, fill them with items using 
AppendMenu, and place them in the menu bar using InsertMenu. 

« Allocate a menu with NewMenu, fill it with items using AddResMenu 
to get the names of all available resources of a given type, and 
place the menu in the menu bar using InsertMenu. 


You can use AddResMenu or InsertResMenu to add items from resource files to any 
menu, regardless of how you created the menu or whether it already contains any 
items. 


When you no longer need a menu, call the Resource Manager procedure 
ReleaseResource if you read the menu from a resource file, or DisposeMenu if you 
allocated it with NewMenu. 


Note: If you want to save changes made to a menu that was read from a 
resource file, write it back to the resource file before calling 
ReleaseResource. 


If you call NewMenu to allocate a menu, it will store a handle to the standard 
menu definition procedure in the menu record, so if you want the menu to be one 
you've designed, you must replace that handle with a handle to your own menu 
definition procedure. For more information, see "Defining Your Own Menus". 


After setting up the menu bar, you need to draw it with the DrawMenuBar 
procedure. 


You can use the SetItem and GetItem procedures to change or examine a menu 
item's text at any time—for example, to change between the two forms of a 
toggled command. You can set or examine an item's icon, style, or mark with the 
procedures SetItemIcon, GetItemIcon, SetItemStyle, GetItemStyle, CheckItem, 
SetItemMark, and GetItemMark. Individual items or whole menus can be enabled or 
disabled with the EnableItem and DisableItem procedures. You can change the 
number of menus in the menu list with InsertMenu or DeleteMenu, remove all the 
menus with ClearMenuBar, or change the entire menu list with GetNewMBar or 
GetMenuBar followed by SetMenuBar. 


When your application receives a mouse-down event, and the Window Manager's 
FindWindow function returns the predefined constant inMenuBar, your application 
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should call the Menu Manager's MenuSelect function, supplying it with the point 
where the mouse button was pressed. MenuSelect will pull down the appropriate 
menu, and retain control—tracking the mouse, highlighting menu items, and 
pulling down other menus—until the user releases the mouse button. MenuSelect 
returns a long integer to the application: The high-order word contains the 
menu ID of the menu that was chosen, and the low-order word contains the menu 
item number of the item that was chosen. The menu item number is the index, 
starting from 1, of the item in the menu. If no item was chosen, the high-order 
word of the long integer is 0, and the low-order word is undefined. 


e If the high-order word of the long integer returned is 0, the application 
should just continue to poll for further events. 

e If the high-order word is nonzero, the application should invoke the menu 
item specified by the low-order word, in the menu specified by the 
high-order word. Only after the action is completely finished (after all 
dialogs, alerts, or screen actions have been taken care of) should the 
application remove the highlighting from the menu bar by calling 
HiliteMenu(0), signaling the completion of the action. 


Note: The Menu Manager automatically saves and restores the bits behind the 
menu; you don't have to worry about it. 


Keyboard equivalents are handled in much the same manner. When your application 
receives a key-down event with the Command key held down, it should call the 
MenuKey function, supplying it with the character that was typed. MenuKey will 
return a long integer with the same format as that of MenuSelect, and the 
application can handle the long integer in the manner described above. 
Applications should respond the same way to auto-key events as to key-down 
events when the Command key is held down if the command being invoked is 
repeatable. 


Note: You can use the Toolbox Utility routines LoWord and HiWord to extract 
the high- order and low-order words of a given long integer, as 
described in the Toolbox Utilities chapter. 


There are several miscellaneous Menu Manager routines that you normally won't 
need to use. CalcMenuSize calculates the dimensions of a menu. CountMItems 
counts the number of items in a menu. GetMHandle returns the handle of a menu in 
the menu list. FlashMenuBar inverts the menu bar. SetMenuFlash controls the 
number of times a menu item blinks when it's chosen. 


The following section describes how to use the new Menu Manager routines 
implemented for the Macintosh Plus, Macintosh SE, and Macintosh II. It also 
explains how changes to previously existing routines affect Menu Manager 
functions. Several of the new features and calls have interesting side effects 
that aren't immediately obvious. If your application is running on a machine 
that can only produce a black-and-white display, any color information is 
ignored, and color icons won't be displayed. 


Enable and Disable 
The EnableItem and DisableItem routines have been changed so that they affect 
only the menu and the first 31 items. ALl items beyond 31 are always enabled. 
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The DrawMenuBar routine properly highlights the selected menu title, if one 
exists. 


When a user chooses a disabled menu item—that is, when the mouse-up event occurs 
over a disabled item—MenuSelect returns a zero result. In the past, there was no 
way for an application to determine which disabled item was chosen. A new 
routine, MenuChoice, can now be called after MenuSelect returns a zero result, 
to determine if the mouse was over a disabled item, and if so, what were the 
menu ID and item number. 


Fonts 


The AddResMenu and InsertResMenu routines can recognize when an added 'FONT' or 
'FOND' resource is the name of an International font. If the Script Manager is 
installed, the font name will be displayed in the actual script. GetItemIcon may 
be used to determine the script number of a font item that names an 
International script. SetItemIcon should never be called for font items that are 
International scripts. 


Custom Menu Bars 


You should only use the InitProcMenu routine if your application has a custom 
menu bar defproc. The effect of this routine lasts for the duration of the 
application program only, and the default menu bar defproc is used afterwards. 


Highlighting 


Menu highlighting has been modified, and this affects the MenuSelect, MenuKey, 
HiliteMenu, and FlashMenuBar routines. Previously, a menu title was selected by 
inverting the rectangle that contained the menu title; when the menu became 
deselected, the same rectangle was merely inverted again, returning the title to 
its original state. This menu title inversion was changed for color menus. In 
the color world, it is no longer proper to merely invert the title's rectangle. 
Color inversion often produces unpleasing and/or unreadable results. Your 
application should set the foreground and background colors before drawing a 
selected menu, and then reset the foreground and background colors before 
drawing the deselected (i.e., normal) menu. One important result of this new 
highlighting scheme is that only one menu may be highlighted at a time. 


Hierarchical and Pop-up Menus 


Using hierarchical menus in an application is straightforward. Hierarchical 
menus may be stored as 'MENU' resources, just as regular menus are. To specify 
that a particular menu is hierarchical, pass a "beforeID" of —1 to the 
InsertMenu routine. When InsertMenu gets a —-1, it places the menu in the 
hierarchical portion of the MenuList. Pop-up menus are also stored in the 
hierarchical portion of the MenuList, and like hierarchical menus, are specified 
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by passing a "beforeID" of —1 to InsertMenu. DeleteMenu may be used to remove a 
hierarchical or pop-up menu from the MenuList. 


A submenu is associated with a menu item by reusing two of the fields in the 
MenuInfo data structure. When the itemCmd field has the hex value $1B, the 
itemMark field contains the menuID of the associated hierarchical menu. (These 
two fields are used because an item with a submenu never has a check mark, and 
doesn't have a Command-key equivalent. ) 


The itemMark field is a byte value, which limits hierarchical menu menuIDs to 
values between 0 and 255. The menuIDs 0-235 (inclusive) may be used by 
applications; numbers 236-255 are reserved for desk accessories. 


Because there is no way to arbitrate among desk accessories, each desk accessory 
is responsible for inserting its hierarchical menus when it becomes active, and 

deleting them when it is deactivated. The problem with this scheme is that some 

desk accessories, such as a spelling checker, need to be activated all the time; 
this kind of desk accessory can't use hierarchical menus, since it has no way to 
determine when it should add or delete its menus. 


Attaching a submenu to a menu item is done in one of two ways. One way is to 
place a $1B in the Command-key equivalent byte in the 'MENU' resource. To 
specify which hierarchical menu is the submenu, the hierarchical menu's resource 
ID is placed in the character mark byte in the 'MENU' resource. 


The other way to attach a submenu to a menu item is to call AppendMenu or 
InsMenuItem.The value $1B may be placed after the Command key metacharacter (/) 
to signify that an item has a submenu. The value of the character following the 
mark metacharacter (!) is taken as the menu ID of the submenu. 


The MenuKey routine has been modified to search for Command-key equivalents in 
hierarchical menus. To accomodate future extensions to the Menu Manager, the 
Command key values $1B (Control-[ ) through $1F (Control-_ ) are reserved for 
use by Apple Computer. The MenuKey procedure ignores these five values as 
Command-key equivalents. Until the Apple Standard Keyboard was implemented, it 
was impossible for the user to type a Control-key sequence, so reserving these 
five values will not impose limitations on existing applications. 


Two new procedures, GetItemCmd and SetItemCmd, have been included to facilitate 
hierarchical menu manipulation. GetItemCmd can be used to determine if a menu 
item has a submenu attached. SetItemCmd can be used to attach a submenu to a 
menu item. GetItemMark can be used to determine the ID of the hierarchical menu 
associated with an item. SetItemMark can be used to change the ID of the 
hierarchical menu associated with an item. The GetMHandle routine can be used to 
get a menu handle for a menu, pop-up menu, or hierarchical menu. 


Color 


A number of existing routines have been modified for color menus; these changes 
affect only the Macintosh II. The InitMenus routine attempts to load a menu 
color resource, 'mctb' resource = 0, and if it succeeds, stores those colors in 
the application's menu color information table. This allows the user to specify 
a set of menu colors that will exist across all applications. 
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Calling the GetMenu, GetMenuBar, SetMenuBar, and GetNewMBar routines affects the 
menu color information table. Clear MenuBar disposes both the current MenuList 
and the current menu color information table. 


GetMenu has been modified: it looks for a 'MENU' resource with the resource ID 
equal to the parameter "menuID" and returns a handle to the menu. It also looks 
for a 'mctb' resource with the resource ID equal to the parameter "menuID", and 
if one is found, adds the colors to the current menu color information table. 
DeleteMenu removes all entries from the menu color information table for the 
menuID specified. 


A set of new routines provides access to the menu color information table. 
SetMCEntries allows an application to add new menu colors and GetMCEntry allows 
the application to query a particular menu color. DelMCEntries deletes specified 
menu color information table entries. 


GetMCInfo makes a copy of the current menu color information table, and returns 
a handle to the copy. While GetMenuBar returns the handle to the current 
MenuList, you must also call GetMCInfo if you want the handle to the current 
menu color information table. 


SetMCInfo copies a table of menu color entries into the current table, after 
first disposing of the current table; this routine can be used to set a new menu 
color information table, or restore a table previously saved by GetMCInfo. 
SetMenuBar first disposes of the current MenuList, then makes a copy of the 
MenuList passed as a parameter and makes it the current MenuList. If you also 
want to set the menu color information table, your application must call 
SetMCInfo. 


GetNewMBar first calls GetMenuBar to store the current MenuList. Next, it calls 
ClearMenuBar, thus disposing of the current MenuList as well as the current menu 
color information table. Then it calls GetMenu and InsertMenu for every menu in 
the menu bar. This builds not only a new MenuList, but a new menu color 
information table. Finally, GetNewMBar restores the old MenuList by calling 
SetMenuBar. Notice that it doesn't store the current menu color information 
table before it begins, nor does it restore it upon leaving. Applications should 
bracket a call to GetNewMBar with calls to GetMCInfo and SetMCInfo, as shown in 
the following example: 


CurMCTable := GetMCInfo; {save current menu color info table} 
NewMenuBar := GetNewMenuBar(4); {get new menu bar #4} 

NewMCTable := GetMCInfo; {get new menu color info table} 
SetMCInfo (CurMCTable) ; {restore previous menu color info table} 
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MENU MANAGER ROUTINES 


Initialization and Allocation 
PROCEDURE InitMenus; 


InitMenus initializes the Menu Manager. It allocates space for the menu list (a 
relocatable block in the heap large enough for the maximum-size menu list), and 
draws the (empty) menu bar. Call InitMenus once before all other Menu Manager 
routines. An application should never have to call this procedure more than 
once; to start afresh with all new menus, use ClearMenuBar. 


Note: The Window Manager initialization procedure InitWindows has already 
drawn the empty menu bar; InitMenus redraws it. 


The InitMenus routine now allocates a dynamic MenuList structure with no menus 
or hierarchical menus. After allocating the initial MenuList, it attempts to 
load an 'mctb' resource = 0. If the user has chosen default menu color values, 
this 'mctb' resource = 0 will exist in the System file. If the 'mctb' is loaded, 
the information contained in the resource is added to the menu color information 
table by making a call to SetMCEntries. If there is an 'mctb' resource = 0 among 
the application's resources, this will be loaded instead of the default 'mctb' 
in the System file. 


FUNCTION NewMenu (menuID: INTEGER; menuTitle: Str255) : MenuHandle; 


NewMenu allocates space for a new menu with the given menu ID and title, and 
returns a handle to it. It sets up the menu to use the standard menu definition 
procedure. (The menu definition procedure is read into memory if it isn't 
already in memory.) The new menu (which is created empty) is not installed in 
the menu list. To use this menu, you must first call AppendMenu or AddResMenu to 
fill it with items, InsertMenu to place it in the menu list, and DrawMenuBar to 
update the menu bar to include the new title. 


Application menus should always have positive menu IDs. Negative menu IDs are 
reserved for menus belonging to desk accessories. No menu should ever have a 
menu ID of 0. 


If you want to set up the title of the Apple menu from your program instead of 
reading it in from a resource file, you can use the constant appleMark (defined 
by the Font Manager as the character code for the apple symbol). For example, 
you can declare the string variable 

VAR myTitle: STRING[1]; 
and do the following: 


myTitle :=' '; 
myTitle[1] := CHR(appleMark) 
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To release the memory occupied by a menu that you created with NewMenu, call 
DisposeMenu. 


FUNCTION GetMenu (resourceID: INTEGER) : MenuHandle; 


Assembly-language note: The macro you invoke to call GetMenu from 
assembly Language is named GetRMenu. 


GetMenu returns a menu handle for the menu having the given resource ID. It 
calls the Resource Manager to read the menu from the resource file into a menu 
record in memory. GetMenu stores the handle to the menu definition procedure in 
the menu record, reading the procedure from the resource file into memory if 
necessary. If the menu or the menu definition procedure can't be read from the 
resource file, GetMenu returns NIL. To use the menu, you must call InsertMenu to 
place it in the menu list and DrawMenuBar to update the menu bar to include the 
new title. 


Warning: Call GetMenu only once for a particular menu. If you need the menu 
handle to a menu that's already in memory, use the Resource Manager 
function GetResource. 


To release the memory occupied by a menu that you read from a resource file with 
GetMenu, use the Resource Manager procedure ReleaseResource. 


After loading a 'MENU' resource, GetMenu attempts to load an 'mctb' resource 
with the same resource ID. If an 'mctb' is loaded, all of the entries are added 
to the application's menu color information table by making a call to 
SetMCEntries. 


PROCEDURE DisposeMenu (theMenu: MenuHandle) ; 


Assembly-language note: The macro you invoke to call DisposeMenu from 
assembly Language is named DisposMenu. 


Call DisposeMenu to release the memory occupied by a menu that you allocated 
with NewMenu. (For menus read from a resource file with GetMenu, use the 
Resource Manager procedure ReleaseResource instead.) This is useful if you've 
created temporary menus that you no longer need. 


Warning: Make sure you remove the menu from the menu list (with DeleteMenu) 
before disposing of it. 


Forming the Menus 
PROCEDURE AppendMenu (theMenu: MenuHandle; data: Str255); 


AppendMenu adds an item or items to the end of the given menu, which must 
previously have been allocated by NewMenu or read from a resource file by 
GetMenu. The data string consists of the text of the menu item; it may be blank 
but should not be the empty string. If it begins with a hyphen (-), the item 
will be a dividing line across the width of the menu. As described in the 
section "Creating a Menu in Your Program", the following meta-characters may be 
embedded in the data string: 
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Meta-character Usage 


; or Return Separates multiple items 

ss Followed by an icon number, adds that icon to the item 

| Followed by a character, marks the item with that character 

< Followed by B, I, U, 0, or S, sets the character style 
of the item 

/ Followed by a character, associates a keyboard equivalent 
with the item 

( Disables the item 


Once items have been appended to a menu, they cannot be removed or rearranged. 
AppendMenu works properly whether or not the menu is in the menu list. 


PROCEDURE InsNewItem (theMenu: MenuHandle; itemString: Str255; afterItem); 


When adding an item to a menu using the AppendMenu or InsMenuItem routines, a 
submenu may be attached to the item by using $1B as the command character, and 
the menu ID of the attached submenu as the mark character 


PROCEDURE AddResMenu (theMenu: MenuHandle; theType: ResType); 


AddResMenu searches all open resource files for resources of type theType and 
appends the names of all resources it finds to the given menu. Each resource 
name appears in the menu as an enabled item, without an icon or mark, and in the 
plain character style. The standard Menu Manager calls can be used to get the 
name or change its appearance, as described in the section "Controlling the 
Appearance of Items". 


Note: If the name of your desk accessory appears not to have been sorted 
and is inserted at the end of the Apple menu, the name is missing 
the leading null character. 


Note: So that you can have resources of the given type that won't appear in 
the menu, any resource names that begin with a period (.) or a percent 
Sign (%) aren't appended by AddResMenu. 


Use this procedure to fill a menu with the names of all available fonts or desk 
accessories. For example, if you declare a variable as 


VAR fontMenu: MenuHandle; 
you can set up a menu containing all font names as follows: 


fontMenu := NewMenu(5,'Fonts'); 
AddResMenu( fontMenu, 'FONT' ) 


Warning: Before returning, AddResMenu issues the Resource Manager call 
SetResLoad(TRUE). If your program previously called SetResLoad (FALSE) 
and you still want that to be in effect after calling AddResMenu, 
you'll have to call it again. 


When AddResMenu or InsertResMenu is called for 'FONT' or 'FOND' resources, 
special processing occurs for fontNumbers greater than or equal to $4000, as is 
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the case for international fonts. If the script associated with the font is 
currently active, then the ItemCmd and ItemIcon fields are used to store 
information allowing the font names to be displayed in the correct script. 


There is a known problem with the AddResMenu and InsertResMenu routines, and 
with the menu enable flags, when the number of items is greater than 31. 
Applications should explicitly reenable or redisable all items after calling 
AddResMenu or InsertResMenu. This is because only the first 31 items are 
affected by the enable flags: all items 32 and greater are always enabled. 


PROCEDURE InsertResMenu (theMenu: MenuHandle; theType: ResType; 
afterItem: INTEGER); 


InsertResMenu is the same as AddResMenu (above) except that it inserts the 
resource names in the menu where specified by the afterItem parameter: If 
afterItem is 0, the names are inserted before the first menu item; if it's the 
item number of an item in the menu, they're inserted after that item; if it's 
equal to or greater than the last item number, they're appended to the menu. 


Note: InsertResMenu inserts the names in the reverse of the order that 
AddResMenu appends them. For consistency between applications in 
the appearance of menus, use AddResMenu instead of InsertResMenu if 
possible. 


PROCEDURE InsMenuItem (theMenu: MenuHandle; itemString: Str255; 
afterItem: INTEGER); 


InsMenuItem inserts an item or items into the given menu where specified by the 
afterItem parameter. If afterItem is 0, the items are inserted before the first 
menu item; if it's the item number of an item in the menu, they're inserted 
after that item; if it's equal to or greater than the last item number, they're 
appended to the menu. 


The contents of itemString are parsed as in the AppendMenu procedure. Multiple 
items are inserted in the reverse of their order in itemString. 


PROCEDURE DelMenuItem (menuItemID: INTEGER); 


DelMenuItem removes the item's color entry from the menu color information 
table, and then deletes the item. 


Note: DelMenuItem is intended for maintaining dynamic menus (Such as a 
list of open windows). It should not be used for disabling items; 
you should use DisableItem instead. 


Forming the Menu Bar 
PROCEDURE InsertMenu (theMenu: MenuHandle; beforeID: INTEGER); 


InsertMenu inserts a menu into the menu list before the menu whose menu ID 
equals beforeID. If beforeID is 0 (or isn't the ID of any menu in the menu 
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list), the new menu is added after all others. If the menu is already in the 
menu list or the menu list is already full, InsertMenu does nothing. Be sure to 
call DrawMenuBar to update the menu bar. 


The InsertMenu routine can be used to add a hierarchical menu to the Menulist. 
If beforeID is equal to —1, the menu is a hierarchical menu. If beforeID is 
greater than or equal to zero, the menu is a nonhierarchical menu. 


It isn't necessary for every menu in the hierarchical menu portion of the 
MenuList to be currently in use; that is, attached to a menu item. Hierarchical 
menus that are currently unused, but may be used some time later by the 
application, may be stored there, and attached to menu items only as needed. You 
should realize that this can cause problems if the unattached submenus have 
items with Command-key equivalents, because MenuKey will find these equivalents 
even though the menu is unattached. 


PROCEDURE DrawMenuBar; 


DrawMenuBar redraws the menu bar according to the menu list, incorporating any 
changes since the last call to DrawMenuBar. This procedure should always be 
called after a sequence of InsertMenu or DeleteMenu calls, and after 
ClearMenuBar, SetMenuBar, or any other routine that changes the menu List. 


DrawMenuBar now properly highlights the selected menu title, if there is one. If 
your application program assumed that DrawMenuBar would redraw the menu 
incorrectly, and called HiliteMenu or FlashMenuBar to compensate, what happens 
now is that the menu bar is redrawn properly, and the next call to HiliteMenu or 
FlashMenuBar causes the highlighted title to become unhighlighted. 


PROCEDURE DeleteMenu (menuID: INTEGER); 


DeleteMenu deletes a menu from the menu list. If there's no menu with the given 
menu ID in the menu list, DeleteMenu has no effect. Be sure to call DrawMenuBar 
to update the menu bar; the menu titles following the deleted menu will move 
over to fill the vacancy. 


Note: DeleteMenu simply removes the menu from the list of currently available 
menus; it doesn't release the memory occupied by the menu data structure. 


The DeleteMenu routine removes all color entries from the menu color information 
table for the specified menuID. It first checks the hierarchical portion of the 
MenuList for the menuID and, if it finds it, deletes the menu; it then returns. 
If the menu is not found in the hierarchical portion of the MenuList, the 
regular portion is checked. 


The hierarchical portion of the MenuList is always checked first, so that any 
desk accessories whose hierarchical menu IDs conflict with an application's 
regular menu IDs can call DeleteMenu without deleting the application's menus. 
PROCEDURE ClearMenuBar; 


Call ClearMenuBar to remove all menus from the menu list when you want to start 
afresh with all new menus. Be sure to call DrawMenuBar to update the menu bar. 


Note: ClearMenuBar, like DeleteMenu, doesn't release the memory occupied by 
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the menu data structures; it merely removes them from the menu list. 


You don't have to call ClearMenuBar at the beginning of your program, because 
InitMenus clears the menu list for you. 


ClearMenuBar clears both the MenuList and the application's menu color 
information table. 


FUNCTION GetNewMBar (menuBarID: INTEGER) : Handle; 


GetNewMBar creates a menu list as defined by the menu bar resource having the 
given resource ID, and returns a handle to it. If the resource isn't already in 
memory, GetNewMBar reads it into memory from the resource file. If the resource 
can't be read, GetNewMBar returns NIL. GetNewMBar calls GetMenu to get each of 
the individual menus. 


To make the menu list created by GetNewMBar the current menu list, call 
SetMenuBar. To release the memory occupied by the menu list, use the Memory 
Manager procedure DisposHandle. 


Warning: You don't have to know the individual menu IDs to use GetNewMBar, 
but that doesn't mean you don't have to know them at all: To do 
anything further with a particular menu, you have to know its ID 
or its handle (which you can get by passing the ID to GetMHandle, 
as described in the section "Miscellaneous Routines"). 


GetNewMBar begins by calling ClearMenuBar, which clears both the MenuList and 
the application's menu color information table. Before returning the Handle to 
the new MenuList, it restores the previous MenuList. It doesn't restore the 
previous menu color information table. If that is desired, the application must 
use GetMCInfo before calling GetNewMBar, and call SetMCInfo afterwards. 


FUNCTION GetMenuBar : Handle; 


GetMenuBar creates a copy of the current menu list and returns a handle to the 
copy. You can then add or remove menus from the menu list (with InsertMenu, 
DeleteMenu, or ClearMenuBar), and later restore the saved menu list with 
SetMenuBar. To release the memory occupied by the saved menu list, use the 
Memory Manager procedure DisposHandle. 


Warning: GetMenuBar doesn't copy the menus themselves, only a list 
containing their handles. Do not dispose of any menus that 
might be in a saved menu list. 


PROCEDURE SetMenuBar (menuList: Handle); 


SetMenuBar copies the given menu list to the current menu list. You can use this 
procedure to restore a menu list previously saved by GetMenuBar, or pass it a 
handle returned by GetNewMBar. Be sure to call DrawMenuBar to update the menu 
bar. 


Choosing From a Menu 
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FUNCTION MenuSelect (startPt: Point) : LONGINT; 


When there's a mouse-down event in the menu bar, the application should call 
MenuSelect with startPt equal to the point (in global coordinates) where the 
mouse button was pressed. MenuSelect keeps control until the mouse button is 
released, tracking the mouse, pulling down menus as needed, and highlighting 
enabled menu items under the cursor. When the mouse button is released over an 
enabled item in an application menu, MenuSelect returns a long integer whose 
high-order word is the menu ID of the menu, and whose low-order word is the menu 
item number for the item chosen (see Figure 4). It leaves the selected menu 
title highlighted. After performing the chosen task, your application should 
call HiliteMenu(0) to remove the highlighting from the menu title. 


If no choice is made, MenuSelect returns 0 in the high-order word of the long 
integer, and the low-order word is undefined. This includes the case where the 
mouse button is released over a disabled menu item (such as Cut, Copy, Clear, or 
one of the dividing lines in Figure 4), over any menu title, or outside the 
menu. In the case of a disabled menu item, an application can still determine 
which item was chosen. See the description of the MenuChoice routine for 
further details. 


If the mouse button is released over an enabled item in a menu belonging to a 
desk accessory, MenuSelect passes the menu ID and item number to the Desk 
Manager procedure SystemMenu for processing, and returns 0 to your application 
in the high-order word of the result. 


Note: When a menu is pulled down, the bits behind it are stored as a 
relocatable object in the application heap. If your application 
has large menus, this can temporarily use up a lot of memory. 
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Figure 4—MenuSelect and Menukey 


Assembly- language note: 


Figure 4—MenuSelect and MenuKey 


If the global variable MBarEnable is nonzero, 
MenuSelect knows that every menu currently in 
the menu bar belongs to a desk accessory. (See 
the Desk Manager chapter for more information. ) 


You can store in the global variables MenuHook and 
MBarHook the addresses of routines that will be called 
during MenuSelect. Both variables are initialized to 

0 by InitMenus. The routine whose address is in 
MenuHook (if any) will be called repeatedly (with no 
parameters) while the mouse button is down. The 
routine whose address is in MBarHook (if any) will 

be called after the title of the menu is highlighted 
and the menu rectangle is calculated, but before the 
menu is drawn. (The menu rectangle is the rectangle in 
which the menu will be drawn, in global coordinates. ) 
The routine is passed a pointer to the menu rectangle 
on the stack. It should normally return 0 in register 
DO; returning 1 will abort MenuSelect. 


If the user chooses an item with a submenu, MenuSelect returns zero, meaning 
that no item was selected. If the user selects an item from a hierarchical menu, 
the menuID of the hierarchical menu and the menuItem of the item chosen are 
returned, just as though the item had been in a regular menu. 
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If MenuSelect returns zero, an application may call MenuChoice to determine 
whether the mouse was released over either a disabled menu item or an item with 
a submenu. 


Note: The global variable TheMenu contains the ID of the highlighted menu in 
the menu bar. If an item from a hierarchical menu is chosen, TheMenu 
contains the ID of the "owner" menu, not the ID of the hierarchical menu. 


FUNCTION MenuKey (ch: CHAR) : LONGINT; 


MenuKey maps the given character to the associated menu and item for that 
character. When you get a key-down event with the Command key held down-or an 
auto-key event, if the command being invoked is repeatable—call MenuKey with the 
character that was typed. MenuKey highlights the appropriate menu title, and 
returns a long integer containing the menu ID in its high-order word and the 
menu item number in its low-order word, just as MenuSelect does (see Figure 4 
above). After performing the chosen task, your application should call 
HiliteMenu(0) to remove the highlighting from the menu title. 


If the given character isn't associated with any enabled menu item currently in 
the menu list, MenuKey returns 0 in the high-order word of the long integer, and 
the low-order word is undefined. 


If the given character invokes a menu item in a menu belonging to a desk 
accessory, MenuKey (like MenuSelect) passes the menu ID and item number to the 
Desk Manager procedure SystemMenu for processing, and returns © to your 
application in the high-order word of the result. 


Note: There should never be more than one item in the menu list with the 
same keyboard equivalent, but if there is, MenuKey returns the first 
such item it encounters, scanning the menus from right to left and 
their items from top to bottom. 


The MenuKey routine first searches for the given key in the regular portion of 
the MenuList, and if it doesn't find it there, searches for the key in the 
hierarchical portion of the MenuList. If the key is in a hierarchical menu, 
MenuKey highlights the menu title of the menu that "owns" the hierarchical menu. 
Ownership in this case means the menu in the menu bar that the user would first 
encounter on the way to the item with the given Command-key equivalent. Because 
several levels of hierarchy are possible, this traversal may not always be 
obvious to the user. As before, after performing the chosen task, your 
application should call HiliteMenu(0) to remove the highlighting from the menu 
title. 


Note: The Command-key codes $1B (Control-[ ) through $1F (Control- _ ) are 
reserved by Apple Computer to indicate meanings other than Command-key 
equivalents. These key codes are ignored by MenuKey, and a result of 
zero is always returned. Applications must never use these codes for 
their own use. 


The global variable TheMenu contains the ID of the highlighted menu in the menu 
bar. If an item from a hierarchical menu is chosen, TheMenu contains the ID of 
the "owner" menu, not the ID of the hierarchical menu. 
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It's possible, although undesirable, to define so-called "circular" hierarchical 
menus. A circular hierarchical menu is one in which a submenu has an "ancestor" 
that is also one of its "offspring". If MenuKey detects circular hierarchical 
menus, a SysError = 86 = #DSHMenuFndErr is generated. 


PROCEDURE HiliteMenu (menuID: INTEGER); 


HiliteMenu highlights the title of the given menu, or does nothing if the title 
is already highlighted. Since only one menu title can be highlighted at a time, 
it unhighlights any previously highlighted menu title. If menuID is 0 (or isn't 
the ID of any menu in the menu list), HiliteMenu simply unhighlights whichever 
menu title is highlighted (if any). 


After MenuSelect or MenuKey, your application should perform the chosen task and 
then call HiliteMenu(0) to unhighlight the chosen menu title. 


Assembly-language note: The global variable TheMenu contains the menu ID 
of the currently highlighted menu. 


Previously, highlighting a menu title meant inverting the title rectangle, and 
dehighlighting it meant reinverting it, so that it returned to normal. With 
color titles, color inversion is usually aesthetically unacceptable, so there is 
a need to draw the highlighted menu title. 


HiliteMenu begins by restoring the bits behind the currently highlighted title 
(if there is one). It then saves the bits behind the title rectangle, and draws 
the highlighted title. HiliteMenu(0) dehighlights the currently highlighted menu 
by restoring the bits behind the title. 


Note: Because an application can only save the bits behind the menu title, 
only one menu title can be highlighted at a time. 


Controlling the Appearance of Items 
PROCEDURE SetItem (theMenu: MenuHandle; item: INTEGER; itemString: Str255); 


SetItem changes the text of the given menu item to itemString. It doesn't 
recognize the meta-characters used in AppendMenu; if you include them in 
itemString, they will appear in the text of the menu item. The attributes 
already in effect for this item—its character style, icon, and so on—remain in 
effect. ItemString may be blank but should not be the empty string. 


Note: It's good practice to store the text of itemString in a resource 
file instead of passing it directly. 


Use SetItem to change between the two forms of a toggled command—for example, to 
change "Show Clipboard" to "Hide Clipboard" when the Clipboard is already 
showing. 


Note: To avoid confusing the user, don't capriciously change the text 
of menu items. 


PROCEDURE GetItem (theMenu: MenuHandle; item: INTEGER; 
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VAR itemString: Str255); 


GetItem returns the text of the given menu item in itemString. It doesn't place 
any meta-characters in the string. This procedure is useful for getting the name 
of a menu item that was installed with AddResMenu or InsertResMenu. 


PROCEDURE DisableItem (theMenu: MenuHandle; item: INTEGER); 


Given a menu item number in the item parameter, DisableItem disables that menu 
item; given 0 in the item parameter, it disables the entire menu. 


Disabled menu items appear dimmed and are not highlighted when the cursor moves 
over them. MenuSelect and MenuKey return 0 in the high-order word of their 
result if the user attempts to invoke a disabled item. Use DisableItem to 
disable all menu choices that aren't appropriate at a given time (such as a Cut 
command when there's no text selection). 


All menu items are initially enabled unless you specify otherwise (such as by 
using the "(" meta- character in a call to AppendMenu) . 


When you disable an entire menu, call DrawMenuBar to update the menu bar. The 
title of a disabled menu and every item in it are dimmed. 


The EnableItem and DisableItem routines provide enable flags that can handle the 
title and 31 menu items. All items greater than 31 will be ignored by these 
calls and will always be enabled. 


PROCEDURE EnableItem (theMenu: MenuHandle; item: INTEGER); 


Given a menu item number in the item parameter, EnableItem enables the item 
(which may have been disabled with the DisableItem procedure, or with the "(" 
meta-character in the AppendMenu string).Given 0 in the item parameter, 
EnableItem enables the menu as a whole, but any items that were disabled 
separately (before the entire menu was disabled) remain so. When you enable an 
entire menu, call DrawMenuBar to update the menu bar. 


The item or menu title will no longer appear dimmed and can be chosen like any 
other enabled item or menu. 


PROCEDURE CheckItem (theMenu: MenuHandle; item: INTEGER; checked: BOOLEAN); 


CheckItem places or removes a check mark at the left of the given menu item. 
After you call CheckItem with checked=TRUE, a check mark will appear each 
subsequent time the menu is pulled down. Calling CheckItem with checked=FALSE 
removes the check mark from the menu item (or, if it's marked with a different 
character, removes that mark). 


Menu items are initially unmarked unless you specify otherwise (such as with the 
"I" meta-character in a call to AppendMenu). 


PROCEDURE SetItemMark (theMenu: MenuHandle; item: INTEGER; markChar: CHAR); 


Assembly-language note: The macro you invoke to call SetItemMark from 
assembly Language is named SetItmMark. 
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SetItemMark marks the given menu item in a more general manner than CheckItem. 
It allows you to place any character in the system font, not just the check 
mark, to the left of the item. The character is passed in the markChar 
parameter. 


Note: The Font Manager defines constants for the check mark and other special 
characters that can't normally be typed from the keyboard: the apple 
symbol, the Command key symbol, and a diamond symbol. See the Font 
Manager chapter for more information. 


To remove an item's mark, you can pass the following predefined constant in the 
markChar parameter: 


CONST noMark = 0; 


The SetItemMark procedure allows the application to change the submenu 
associated with a menu item. 


PROCEDURE GetItemMark (theMenu: MenuHandle; item: INTEGER; 
VAR markChar: CHAR); 


Assembly-language note: The macro you invoke to call GetItemMark from 
assembly Language is named GetItmMark. 


GetItemMark returns in markChar whatever character the given menu item is marked 
with, or the predefined constant noMark if no mark is present. 


The GetItemMark procedure may be used to determine the ID of the hierarchical 
menu associated with a menu item. 


PROCEDURE SetItemIcon (theMenu: MenuHandle; item: INTEGER; icon: Byte); 


Assembly-language note: The macro you invoke to call SetItemIcon from 
assembly Language is named SetItmIcon. 


SetItemIcon associates the given menu item with an icon. It sets the item's icon 
number to the given value (an integer from 1 to 255). The Menu Manager adds 256 
to the icon number to get the icon's resource ID, which it passes to the 
Resource Manager to get the corresponding icon. 


Warning: If you call the Resource Manager directly to read or store 
menu icons, be sure to adjust your icon numbers accordingly. 


Menu items initially have no icons unless you specify otherwise (such as with 
the "*" meta-character in a call to AppendMenu). 


The SetItemIcon procedure should never be called for font items that are 
international scripts, unless the intention is to change the script number 
(there should never be any need to do this). 

PROCEDURE GetItemIcon (theMenu: MenuHandle; item: INTEGER; VAR icon: Byte); 


Assembly-language note: The macro you invoke to call GetItemIcon from 
assembly Language is named GetItmIcon. 
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GetItemIcon returns the icon number associated with the given menu item, as an 
integer from 1 to 255, or 0 if the item has not been associated with an icon. 
The icon number is 256 less than the icon's resource ID. 


The GetItemIcon procedure may be used to determine the script number of a font 
item that is the name of an international script. 


PROCEDURE SetItemStyle (theMenu: MenuHandle; item: INTEGER; chStyle: Style); 


Assembly-language note: The macro you invoke to call SetItemStyle from 
assembly Language is named SetItmStyle. 


SetItemStyle changes the character style of the given menu item to chStyle. For 
example: 


SetItemStyle(thisMenu,1, [bold, italic] ) {bold and italic} 


Menu items are initially in the plain character style unless you specify 
otherwise (such as with the "<" meta-character in a call to AppendMenu) . 


PROCEDURE GetItemStyle (theMenu: MenuHandle; item: INTEGER; 
VAR chStyle: Style); 


Assembly-language note: The macro you invoke to call GetItemStyle from 
assembly Language is named GetItmStyle. 


GetItemStyle returns the character style of the given menu item in chStyle. 


There is a possible bug in this routine, depending on the interpretation of the 
address of the VAR parameter chStyle. GetItemStyle assumes that the address on 

the stack points to a word with chStyle in the low byte. MPW Pascal passes the 

byte address of chStyle regardless of whether it's in the high or low byte of a 
word. Since there has never been a bug report for this "problem", it is listed 

here for information only. 


Miscellaneous Routines 

PROCEDURE CalcMenuSize (theMenu: MenuHandle) ; 

You can use CalcMenuSize to recalculate the horizontal and vertical dimensions 
of a menu whose contents have been changed (and store them in the appropriate 
fields of the menu record). CalcMenuSize is called internally by the Menu 
Manager after every routine that changes a menu. 

FUNCTION CountMItems (theMenu: MenuHandle) : INTEGER; 

CountMItems returns the number of menu items in the given menu. 


FUNCTION GetMHandle (menuID: INTEGER) : MenuHandle; 


Given the menu ID of a menu currently installed in the menu list, GetMHandle 
returns a handle to that menu; given any other menu ID, it returns NIL. 
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The GetMHandle routine looks for the menu in the hierarchical portion of the 
MenuList first, and if it isn't found, looks in the regular portion of the 
MenuList. The routine has no way to determine whether the returned menu is 
associated with a menu, pop-up, or hierarchical menu. Presumably the application 
will contain that information. 


PROCEDURE FlashMenuBar (menuID: INTEGER); 


If menuID is 0 (or isn't the ID of any menu in the menu list), FlashMenuBar 
inverts the entire menu bar; otherwise, it inverts the title of the given menu. 
You can call FlashMenuBar(@) twice to blink the menu bar. 


FlashMenuBar(0) still inverts the complete menu bar. Strange colors may result 
if HiliteMenu, or FlashMenuBar with a nonzero parameter, are called while the 
menu bar is inverted. 


FlashMenuBar has been modified so that only one menu may be highlighted at a 
time (see HiliteMenu). If no menu is currently highlighted, calling FlashMenuBar 
with a nonzero parameter highlights that menu. If the highlighted menu is 
different than the one being "flashed", the previously highlighted menu is first 
restored to normal, and the new menu is highlighted. 


PROCEDURE SetMenuFlash (count: INTEGER); 


Assembly-language note: The macro you invoke to call SetMenuFlash from 
assembly Language is named SetMFlash. 


When the mouse button is released over an enabled menu item, the item blinks 
briefly to confirm the choice. Normally, your application shouldn't be concerned 
with this blinking; the user sets it with the Control Panel desk accessory. If 
you're writing a desk accessory like the Control Panel, though, SetMenuFlash 
allows you to control the duration of the blinking. The count parameter is the 
number of times menu items will blink; it's initially 3 if the user hasn't 
changed it. A count of © disables blinking. Values greater than 3 can be 
annoyingly slow. 


Note: Items in both standard and nonstandard menus blink when chosen. The 
appearance of the blinking for a nonstandard menu depends on the menu 
definition procedure, as described in "Defining Your Own Menus". 


Assembly-language note: The current count is stored in the global 
variable MenuFlash. 


New Routines 


The Menu Manager routines listed in this section are implemented for the 
Macintosh Plus, Macintosh SE, and Macintosh II where noted. 


PROCEDURE InitProcMenu (mbResID: INTEGER); 
[Macintosh Plus, Macintosh SE, Macintosh II] 


Note: The mbVariant field is contained in the low three bits of the 
mbResID. The high order 13 bits are used to load the proper 'MBDF'. 
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The InitProcMenu routine is called when an application has a custom menu bar 
defproc, 'MBDF'. InitProcMenu allocates a new MenuList if it hasn't already been 
allocated by a previous call to InitMenus, and the mbResID is stored in the 
mbResID field in the MenuList (note that InitWindows calls InitMenus, so that it 
can obtain the menu bar height). 


The effect of InitProcMenu lasts for the duration of the application only; the 
next InitMenus call will replace the mbResID field in the MenuList with the 
default value of zero. This affects applications such as development systems, 
which use multiple heaps and whose "applications" call InitMenus. 


Note: Apple reserves mbResID values $000-—$100 for its own use. 
PROCEDURE DelMCEntries (MenuID, menuItem: INTEGER); [Macintosh II] 


The DelMCEntries routine deletes entries from the menu color information table 
based on the given menuID and menuItem. If the entry is not found, no entry is 
removed. If the menuItem is mctAllItems (—98), then all Items for the specified 
ID are removed. 


Applications must, of course, never delete the last entry in the menu color 
information table. 


FUNCTION GetMCInfo: MCTableHandle; [Macintosh II] 


The GetMCInfo routine creates a copy of the current menu color information table 
and returns a handle to the copy. It doesn't affect the current menu color 
information table. If the copy fails, a NIL handle is returned. 


PROCEDURE SetMCInfo (menuCTbl : MCTableHandle); [Macintosh II] 


The SetMCInfo routine copies the given menu color information table to the 
current menu color information table. It first disposes of the current menu 
color information table, so your application shouldn't explicitly dispose the 
current table. If the copy fails, the global variable MemErr contains the error 
code, and the procedure doesn't dispose the current menu color information 
table. Applications should call the MemError function to determine if this call 
failed. 


You can use this procedure to restore a menu color information table previously 
saved by GetMCInfo. Be sure to call DrawMenuBar to update the menu bar if a new 
menu bar color or menu title colors have been specified. 


PROCEDURE DispMCInfo (menuCTbl : MCTableHandle); [Macintosh IT] 


Given a handle to a menu color information table, the DispMCInfo routine 
disposes of the table. No checking is done to determine whether the handle is 
valid. While this procedure currently only calls DisposHandle, to ensure 
compatibility with any updates to the color portion of the menu manager, it's a 
good idea to use this call. 


FUNCTION GetMCEntry (menuID, menuItem : INTEGER): MCEntryPtr; [Macintosh II] 
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The GetMCEntry routine finds the entry of the specified menuID and menuItem in 
the menu color information table, and returns a pointer into the table. If the 
entry is not found, a NIL pointer is returned. 


Note: Entries are not removed from the table. Applications must not remove 
entries from the table directly; they should always use the procedure 
DelMCEntries to remove entries. 


Warning: The menu color information table is relocatable, so the GetMCEntry 
return value may not be valid across traps that move or purge memory. 
Applications should make a copy of the record in this case. 


PROCEDURE SetMCEntries (numEntries: INTEGER; menuCEntries: MCTablePtr) ; 
[Macintosh IT] 


The SetMCEntries procedure takes a pointer to an array of color information 
records. The array may be of any size, so it's necessary to also pass the number 
of entries in the array. 


The ID and Item of each entry in the color information record array are checked 
to see if the entry already exists in the menu color information table. If it 
exists, the information in the entry is used to update the entry in the color 
table. If the entry doesn't exist in the color information table, the entry is 
added to the table. 


Warning: SetMCEntries makes memory management calls that may move or purge 
memory; therefore the array menuCEntries should be nonrelocatable 
for the duration of this call. 


FUNCTION MenuChoice : LONGINT; [Macintosh ITI] 


The MenuChoice routine is called only after the result from MenuSelect is zero. 
It determines if the mouse-up event that terminated MenuSelect was in a disabled 
menu item. When the mouse button is released over a disabled item in an 
application menu, MenuChoice returns a long integer whose high-order word is the 
menuID of the menu, and whose low-order word is the menu item number for the 
disabled item "chosen". If the item number is zero, then the mouse-up event 
occurred when the mouse was either in the menu title or completely outside the 
menu; there is no way to distinguish between the two. 


Note: This information is available on the Macintosh Plus and Macintosh SE 
by directly querying the long word stored in the global variable 
MenuDisable ($B54). 


This feature has been added to MenuChoice to make it possible for applications 
to provide better help facilities. For example, when the Finder calls 
MenuChoice, and determines that a user has chosen the disabled menu item “Empty 
Trash" with the Finder, the application could display a message telling the user 
that it can't empty the trash because there is nothing currently in the trash. 


The new MenuChoice capability is implemented by continual updates of the global 
variable MenuDisable ($B54) whenever a menu is down. As the mouse moves over 
each item, MenuDisable is updated to reflect the current menu and item ID. The 
code that changes the value in MenuDisable resides in the standard menu defproc. 
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The return value is undefined when the menu uses a custom menu defproc, unless 
the custom defproc also supports this feature. 


PROCEDURE GetItemCmd (theMenu: menuHandle; item: INTEGER; VAR cmdChar:Char) ; 
[Macintosh Plus, Macintosh SE, Macintosh II] 


The GetItemCmd routine may be used to determine whether a menu item has a 
submenu attached. For a menu item with a submenu, the returned cmdChar will have 
the value $1B. 


PROCEDURE SetItemCmd (theMenu: menuHandle; item: INTEGER; cmdChar:Char) ; 
[Macintosh Plus, Macintosh SE, Macintosh II] 


The SetItemCmd routine allows the application to attach a submenu to a menu by 
passing the character $1B. You should be careful about arbitrarily adding or 
removing a submenu from a menu item; see the Macintosh User Interface Guidelines 
chapter for recommendations. Notice that SetItemMark can be used to change the 
ID of the submenu that is associated with the menu item. 


Note: SetItemCmd must never be used to change the Command-key value of a 
menu item that doesn't have a submenu; users must always be free to 
change their Command-key preferences. 


FUNCTION PopUpMenuSelect (theMenu:menuHandle; 
Top,Left,PopUpItem: INTEGER): LONGINT; 
[Macintosh Plus, Macintosh SE, Macintosh II] 


The PopUpMenuSelect routine allows an application to create a pop-up menu 
anywhere on the screen. This menu may be colored like any other menu, and it may 
have submenus. The return value is the same as that for MenuSelect, where the 
low word is the menu item selected, and the high word is the menu ID. Unlike 
MenuSelect, PopUpMenuSelect doesn't highlight any of the menus in the menu bar, 
so HiliteMenu(0) doesn't have to be called after completing the chosen task. 


Pop-up menus are typically used for lists of items, for example, fonts. See the 
Macintosh User Interface Guidelines chapter for a description of how to use pop- 
up menus in your application. See MenuSelect for information about the return 
value when the menu chosen is a hierarchical menu. 


TheMenu is a handle to the menu that you want "popped up". The PopUpItem is 
typically the currently selected item, that is, the last item selected, or the 
first item if nothing was selected. Doing this allows the user to click ona 
pop-up menu and release again quickly, without changing the item selection by 
mistake. The parameters Top and Left define where the top left corner of the 
PopUpItem is to appear, in global coordinates. Typically, these will be the top 
left coordinates of the pop-up box, so that the menu item appears on top of the 
pop-up box. See Figure 5 for an example. 
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Figure 5—Pop-up Box Parameters 


Figure 5—Pop-up Box Parameters 
Drawing the Pop-Up Box 


Your application is responsible for drawing the pop-up box. A pop-up box is a 
rectangle that is the same height as the menu item, is wide enough to show the 
currently selected item, and has a one-pixel-wide drop shadow. 


The pop-up box must be the same height as a menu item so that when the menu 
appears, the cursor will be in the previously chosen item. If the pop-up box is 
too tall, the user could click once quickly in a pop-up box and unintentionally 
choose a different menu item. The height of a menu item in the system font is 
the ascent + descent + leading. 


The pop-up box has a title to its left. The application is responsible for 
recognizing a mouse-down event in the pop-up box, and highlighting the title to 
the left of the pop-up menu box before calling MenuSelect. Similarly, the 
application is responsible for highlighting the title if the pop-up menu has 
Command-key equivalents. 


Before calling PopUpMenuSelect, the pop-up menu must be installed in the 
hierarchical portion of the MenuList by passing a value of —-1 as the "beforeID" 
to InsertMenu. 


The following is a sample psuedocode stub that might be used to track a pop-up 
menu: 


if mouse is in popUpMenuRect then 
myInvertPopUpTitle(); {invert title of pop-up menu} 
InsertMenu(popupMenuHandle, -1); {-1 means hierarchical menu} 
Result = PopUpMenuSelect(popUpMenuHandle, popUpRect.Top, 
popUpRect.Left, lastItemSelected) ; 
DeleteMenu (popUpMenulID) ; 
myInvertPopUpTitle(); {return pop-up title to normal} 
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endif 


Notice that PopUpMenuSelect's sole function is to display the pop-up menu and 
track the mouse during a mouse-down event. It is the application's 
responsibility to handle all other pop-up menu functions, such as drawing the 
pop-up box, drawing and highlighting the title, and changing the entry in the 
pop-up box after an item has been chosen from the pop-up menu. This could all be 
handled by creating a pop-up menu control within the application. 


When calling PopUpMenuSelect, the pop-up menu must be in the MenuList for the 
duration of the call. The code above shows a call the InsertMenu before, and a 
call to DeleteMenu after, the call to PopUpMenuSelect. The InsertMenu must be 
used at some time before the call to PopUpMenuSelect, but it's not necessary to 
call DeleteMenu immediately afterwards; the pop-up menu may be left in the 
MenuList if desired. 


Pop-up menu items can have Command-key equivalents. The application must provide 
sufficient visual feedback, normally provided by using MenuKey, by inverting the 
pop-up title. 
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DEFINING YOUR OWN MENUS 


The standard type of Macintosh menu is predefined for you. However, you may want 
to define your own type of menu—one with more graphics, or perhaps a nonlinear 
text arrangement. QuickDraw and the Menu Manager make it possible for you to do 
this. 


To define your own type of menu, you write a menu definition procedure and store 
it in a resource file. The Menu Manager calls the menu definition procedure to 
perform basic operations such as drawing the menu. 


A menu in a resource file contains the resource ID of its menu definition 
procedure. The routine you use to read in the menu is GetMenu (or GetNewMBar, 
which calls GetMenu). If you store the resource ID of your own menu definition 
procedure in a menu in a resource file, GetMenu will take care of reading the 
procedure into memory and storing a handle to it in the menuProc field of the 
menu record. 


If you create your menus with NewMenu instead of storing them as resources, 
NewMenu stores a handle to the standard menu definition procedure in the menu 
record's menuProc field. You must replace this with a handle to your own menu 
definition procedure, and then call CalcMenuSize. If your menu definition 
procedure is in a resource file, you get the handle by calling the Resource 
Manager to read it from the resource file into memory. 


The Menu Definition Procedure 


The menu definition procedure is usually written in assembly language, but may 
be written in any high-level language. 


Assembly-language note: The procedure's entry point must be at the beginning. 


You may choose any name you wish for the menu definition procedure. Here's how 
you would declare one named MyMenu: 


PROCEDURE MyMenu (message: INTEGER; theMenu: MenuHandle; VAR menuRect: Rect; 
hitPt: Point; VAR whichItem: INTEGER); 


The message parameter identifies the operation to be performed. It has one of 
the following values: 


CONST mDrawMsg 
mChooseMsg 
mSizeMsg 


0; {draw the menu} 
1; {tell which item was chosen and highlight it} 
2; {calculate the menu's dimensions} 


The parameter theMenu indicates the menu that the operation will affect. 
MenuRect is the rectangle (in global coordinates) in which the menu is located; 
it's used when the message is mDrawMsg or mChooseMsg. 
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Note: MenuRect is declared as a VAR parameter not because its value is 
changed, but because of a Pascal feature that will cause an error 
when that parameter isn't used. 


The message mDrawMsg tells the menu definition procedure to draw the menu inside 
menuRect. The current grafPort will be the Window Manager port. (For details on 
drawing, see the QuickDraw chapter.) The standard menu definition procedure 
figures out how to draw the menu items by looking in the menu record at the data 
that defines them; this data is described in detail under "Formats of Resources 
for Menus" below. For menus of your own definition, you may set up the data 
defining the menu items any way you like, or even omit it altogether 

(in which case all the information necessary to draw the menu would be in the 
menu definition procedure itself). You should also check the enableFlags field 
of the menu record to see whether the menu is disabled (or whether any of the 
menu items are disabled, if you're using all the flags), and if so, draw it in 
gray. 


Note: MenuKey will always search the menuData field of a MenuInfo record for 
Command-key equivalents until it finds a zero where a standard menu 
title should be, even if the MenuInfo record is for one of your own 
'MDEF' resources. To prevent MenuKey from finding a Command-key 
equivalent in your MenuInfo record, put a couple of bytes of zeros 
just after the menu's title. 


Warning: Don't change the font from the system font for menu text. 
(The Window Manager port uses the system font.) 


When the menu definition procedure receives the message mChooseMsg, the hitPt 
parameter is the mouse location (in global coordinates), and the whichItem 
parameter is the item number of the last item that was chosen from this menu 
(whichItem is initially set to 0). The procedure should determine whether the 
mouse location is in an enabled menu item, by checking whether hitPt is inside 
menuRect, whether the menu is enabled, and whether hitPt is in an enabled menu 
item: 


¢ If the mouse location is in an enabled menu item, unhighlight whichItem 
and highlight the new item (unless the new item is the same as the 
whichItem), and return the item number of the new item in whichItem. 

e If the mouse location isn't in an enabled item, unhighlight whichItem 
and return 0. 


Note: When the Menu Manager needs to make a chosen menu item blink, it 
repeatedly calls the menu definition procedure with the message 
mChooseMsg, causing the item to be alternately highlighted and 
unhighlighted. 


Finally, the message mSizeMsg tells the menu definition procedure to calculate 
the horizontal and vertical dimensions of the menu and store them in the 
menuWidth and menuHeight fields of the menu record. 


The following section describes changes to the default menu definition procedure 
('MDEF' resource 0); some of the information presented in this section is 
accessible only through assembly Language. 


Note: These features will work with the 64K ROM if the new menu definition 
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procedure is in the system resource file. 


Variable Size Fonts 


Menus are displayed in the system font. Since the system font and font size can 
now be changed, the menu definition procedure calls the QuickDraw procedure 
GetFontInfo for the system font to determine the height of menu items 


Scrolling Menus 


The default menu definition procedure allows longer menus by implementing 
automatic scrolling. If the entire menu cannot be drawn on screen, dragging the 
cursor below the last displayed item will cause the items in the menu to scroll 
up. Similarly, if items have been scrolled past the top of the menu, dragging 
the cursor into the highlighted portion of the menu bar will cause the menu to 
scroll back down. The maximum number of items that can be drawn on the standard 
Macintosh screen with this new menu definition function is 19 (instead of 20). 


Warning: You should not disable any menu items in a menu containing more than 
31 items because the enableFlags field of the MenuInfoRec can only 
handle 31 items. 
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THE STANDARD MENU DEFINITION PROCEDURE 


This section describes changes made to the default menu definition procedure 
'MDEF' resource = 0, for all Macintoshes except the 64K and 512K versions. The 
'MDEF' resource has been modified to ignore all undefined messages. Any custom 
'MDEF' should do the same. This allows Apple to define new messages (as 
described below for pop-up menus) without impacting custom 'MDEF' resources. 
Apple recognizes that applications may want to call their custom defprocs for 
information, and has reserved all messages above and including 128 for 
application use. Apple's defprocs will ignore all messages above and including 
128. 


For the latest standard 'MDEF', the version number = 10. Version 10 and all 
later versions include the features Listed below. 


For hierarchical menus: 


e The triangular marker indicating that an item has a submenu appears 
in the location where the Command-key equivalent is normally shown. 

« The Command-key values $1B (Control-[ ) through $1F (Control-_ ) are 
reserved by Apple to have meanings other than command keys. 


For scrolling menus: 


e When a menu is scrollable, scrolling indicators appear. If the menu 
scrolls up, a triangular indicator appears in place of the last item 
in the list, and if the menu scrolls down, an indicator appears in place 
of the first item in the list. The menu scrolls when the cursor is moved 
into the area of the indicator, or is directly above or below the menu. 


For pop-up menus: 
e A new message has been added to the standard 'MDEF' resource. Message #3, 


pop-up menu placement, asks the defproc to calculate the menu rectangle 
of the pop-up menu. 


Parameter On Entry Return Value 

message 3 

theMenu menuHandle 

menuRect Pop-up menu's rectangle 
hitPt Top left of PopupItem 

whichItem PopupItem Top of menu if menu scrolls 


When a pop-up menu appears, the menu is adjusted on the screen so that 
the previously selected item appears on top of the pop-up menu box. The 
previously selected item is passed in the parameter whichItem, and the 
top left corner of the pop-up menu box is passed in hitPt. On exit, the 
rectangle in which the pop-up menu is to appear is returned in menuRect. 
If the menu is so large that it scrolls, then the actual top of the menu 
is returned in whichItem. 
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eeeClick on the X-Ref button, and refer to Technical Note #172.¢e¢«¢ 


e When a defproc draws a pop-up menu, its scrolling information must be 
placed in the global variables TopMenuItem and AtMenuBottom. 


For color menus (Macintosh II only): 


¢ When menu items are drawn, the background of the menu has already been 
erased to the color specified for that menu in the menu color information 
table, or to white if none is specified. When the mark, item, and 
Command-key equivalent fields are drawn, the menu defproc checks the menu 
color information table for the colors to use. If there is an item entry, 
those colors are used. If there is no item entry, then the default from 
the title entry is used. If there is no title entry, then the default from 
the menu bar entry is used. If there is no menu bar entry, then black on 
white is used. 

« When an item is chosen, the background color and the item color are 
reversed, and the item is redrawn in those colors. When an item is chosen, 
the background color and item color are reset, and the item is redrawn in 
those colors. 

¢ If your application uses the standard menu bar defproc to draw menu items 
into menus after saving the bits behind and drawing the drop shadow, it 
must erase the menu's background to the correct color. If this isn't done 
when the user has set default menu colors, incorrect colors and unreadable 
items can result. 

¢ Custom menu defprocs that use color items must provide the menu background 
color. When the standard 'MBDF' clears the menu background and draws the 
drop shadow, it clears the menu background to whatever color is specified 
in the menu color information table. Custom menu defprocs should either 
(1) support color items by accessing the menu color information table or 
(2) erase the background of the menu to white before drawing color items. 


All menus: 


¢ The menu defproc sets the global variable MenuDisable ($B54) each time a 
new item is highlighted. After MenuSelect returns a zero, your application 
can query MenuDisable directly, or use MenuChoice, to determine which menu 
ID and menu item were chosen. 

¢ The value returned by MenuChoice will be undefined if the last menu 
displayed has a custom 'MDEF'. When including a custom 'MDEF' in your 
application, you should consider supporting MenuChoice so that desk 
accessories providing on-line help for the application will be able to 
Support all its menus. 

e Any application that uses the standard 'MDEF' to draw menu items must set 
the global variable TopMenuItem ($A0A). This variable is used by the 
standard 'MDEF' to determine if scrolling is necessary. If TopMenuItem 
isn't set properly, scrolling might occur when it shouldn't. TopMenuItem 
should contain global coordinates indicating where the first item in the 
menu is to be drawn; typically this is the same as the top of the menu 
rectangle. However, your application can use other coordinates if you 
don't want the first menu item to appear at the top of the menu rectangle. 
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THE STANDARD MENU BAR DEFINITION PROCEDURE 


To give application writers more control over custom menus, a default menu bar 
definition procedure has been added. This section describes the default menu bar 
definition procedure ('MBDF' resource = 0). On the Macintosh II, the menu bar 
defproc provides support for color, pop-up, and hierarchical menus, as well as 
standard menus. This new defproc supplements the existing standard 'MDEF' 
resource. 


ALL menu drawing-related activities, previously included in the routines 
DrawMenuBar, MenuSelect, MenuKey, HiliteMenu, and FlashMenuBar, have been 
removed from the menu manager code, and placed in the menu bar defproc. Using 
the menu bar defproc with the menu defproc gives the application writer complete 
control over the appearance and use of menus. 


An application that specifies its own menu bar defproc should call InitProcMenu 
instead of InitMenus, which then loads the appropriate 'MBDF' resource. 


There are currently 13 messages defined for the menu bar defproc: 


Msg # Msg Description 
0 Draw Draws the menu bar or clears the menu bar. 
1 Hit Tests to see if the mouse is in the menu bar 
or any currently displayed menus. 
2 Calc Calculates the left edges of each menu title in 
the MennuList data structure. 
3 Init Initializes any menu bar defproc data structures. 
4 Dispos Disposes of any menu bar defproc data structures. 
5 Hilite Highlights the specified menu title, or inverts 
the whole menu bar. 
6 Height Returns the menu bar height. 
7 Save Saves the bits behind a menu and draws the menu structure. 
8 Restor Restores the bits behind a menu. 
9 Rect Calculates the rectangle of a menu. 
10 SaveALt Saves more information about a menu after it has been drawn. 
11 ResetAlt Resets information about a menu. 
12 MenuRgn Returns a region for the menu bar. 


Custom 'MBDF' defprocs should ignore messages that are not currently defined in 
this documentation. Messages numbered 128 and above are reserved for custom 
defprocs. 


You may choose any name you wish for the menu bar defproc. The following example 
declares a menu bar defproc named MyMenuBar: 


FUNCTION MyMenuBar ( selector: INTEGER; message: INTEGER; 
parameterl: INTEGER: 
parameter2: LONGINT): LONGINT; 
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Parameters for Menu Bar Defproc Messages 


This section lists the parameters for each message. Note that the menu bar 
defproc draws directly into the window manager port, or color window manager 
port if there is one. Any time the menu bar defproc draws in the Window Manager 
port (or color port) it clips the port to full open before it returns. Full open 
is defined to be the portRect of the Window Manager, or the color Window Manager 
port. The exception to this rule is that the Draw message leaves the Window 
Manager port (or color port) clipped to the menu bar when parameter2 = -1. See 
the individual message descriptions for more information. 


Message #0: Draw: 


Called By Selector Parameterl Parameter2 Result 
Window Manager mbVariant none —1 = clear bar none 
DrawMenuBar 0 = draw bar 


When parameter2 = 0 (zero), the menu bar is cleared to the proper color, the 
titles are drawn, and the window manager port clip region is set to full open. 
After all of the titles are drawn, if one of the titles is currently selected 
(its menuID is contained in the global variable TheMenu ($A26)), then the title 
is highlighted. DrawMenuBar passes parameter2 = 0. 


When parameter2 = —1 the menu bar is cleared to the proper color, no titles are 
drawn, and the Window Manger port clip region is set to the menu bar. The 
Window Manager passes parameter2 = -1. 


Message #1: Hit 


Called By Selector Parameterl Parameter2 Result 
FindwWindow mbVariant none mouse pt 0 = in bar, 
no title hit 
MenuSelect —1 = not in bar 
<poOs> = 


Six-byte offset 


The mouse point to be tested for its location is passed in parameter2. First 
this message checks to see whether the mouse point is in the menu bar. If it is 
in the menu bar, then the message further checks whether the mouse is in any 
menu title. If the mouse is in the menu bar but not in a title, the result is 
0. If the mouse is in a title, the result is the offset of the title in the 
menuList. The notation <pos> refers to a result which is a positive value 
(greater than zero). A six-byte offset refers to the offset of a menu in the 
menuList data structure. 


If the mouse is not in the menu bar, this message tests whether mouse point is 
in any currently visible menu. If more than one menu is visible—that is, one or 
more hierarchical menus are visible—the message searches through those menus 
backwards, checking the topmost hierarchical menu first. If the mouse point is 
found to be in a currently visible menu, the result is the six-byte offset of 
that menu in the menuList. 
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Message #2: Calc 


Called By Selector Parameterl Parameter2 Result 
InsertMenu mbVariant none 0 = all none 
DeleteMenu <pos> = six-byte 

offset 


This message calculates the lastRight and menuLeft fields in the menuList. If 


parameter2 = 0 then the calculation is done for all of the 


menus. 


If parameter2 


= the offset of a title in the menuList, then the calculation begins with that 
menu and continues for all following menus. A six-byte offset refers to the 
offset of a menu in the menuList data structure. The notation <pos> refers to a 


result which is a positive value (greater than zero). 


Message #3: Init 


Called By Selector Parameterl Parameter2 
InitMenus mbVariant none none 
InitProcMenu 


Result 


none 


This message creates a data structure in the system heap the first time it is 
called after system startup. It clears the field lastMBSave in that data 


structure at every call thereafter. 


This message is called by InitProcMenu if the MenuList data structure hasn't 
been allocated. Applications that switch menu defprocs on the fly, and call 
InitProcMenu to do so, will need to call the 'MBDF' with the "Init" message to 


execute this message. 

Message #4: Dispose 

Called By Selector Parameterl Parameter2 
- mbVariant none none 

Currently, this message does nothing. 


Message #5: Hilite 


Called By Selector Parameterl Parameter2 
MenuSelect mbVariant none <packed> 
HiliteMenu 

FlashMenuBar 


Result 


none 


Result 


none 


Parameter2 contains a packed value: the high word contains the highlight state 
desired, and the low word contains the menu to be highlighted, which is its six- 
byte offset in the menuList. The <packed> notation refers to the following: high 
word 0 = normal, high word 1 = selected, low word 0 = flipbar. A highlight state 
of 1 (one) means the title is to be selected, and a highlight state of 0 


(zero) means that the title is to be returned to normal. 
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When a menu is selected, the bits behind the title are saved. Next, the color 
of the title and the color of the menu bar are reversed, and the title is 
redrawn in these reversed colors. Reversing the colors simply means setting the 
background color to the title color and the foreground color to the menu bar 
color. This is necessary because merely inverting the title rectangle with a 
call to InvertRect, as was done on previous machines, often produces unpleasing 
and/or unreadable results. 


When a menu is deselected—that is, the highlight state is 0 (zero)-—the bits 
behind the title are restored. If there was not enough memory to save the bits 
behind the title, DrawMenuBar is called to redraw the whole menu bar. 


If the low word of parameter2 is zero, the whole menu bar is inverted. 
FlashMenuBar uses this feature. 


Message #6: Height 

Called By Selector Parameterl Parameter2 Result 

Window Manager mbVariant none none none 

This calculates the menu bar height by looking at the size of the system font, 
and stores that value in the global variable MBarHeight ($BAA). Note that the 


Window Manager assumes that the menu bar is at the top of the screen. 


Message #7: Save 


Called By Selector Parameterl Parameter2 Result 
MenuSelect mbVariant six-byte offset menuRect none 
PopUpMenuSelect 


Parameter2 is the rectangle into which the menu is to be drawn. Parameterl is 
the offset into the menuList of the menu to be drawn. A six-byte offset refers 
to the offset of the menu into the menuList data structure. First the bits 
behind the menu are saved. Next the menu rectangle is erased to the proper 
background color, and the menu structure (i.e., shadow) is drawn. Finally, 
various information about the menu is stored in the menu bar defproc's data 
structure. 


Message #8: Restore 


Called By Selector Parameterl Parameter2 Result 
MenuSelect mbVariant none none none 
PopUpMenuSelect 


No parameters are passed; the assumption is that the last displayed menu will 
always be the first one restored. If there was not enough memory to save the 
bits behind the menu, an update event is generated for the menu rectangle. 
Message #9: GetRect 


Called By Selector Parameterl Parameter2 Result 
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MenuSelect mbVariant none <packed2> menuRect 
PopUpMenuSelect 


Parameter2 contains the offset into the menuList data structure for the menu 
whose rectangle is to be calculated, as well as information about whether this 
is for a regular menu or a hierarchical menu. The <packed2> notation refers to 
the following: high word 0 = regular menu, high word nonzero = mouse 
pt/hierarchical menu, low-word = six-byte offset of a menu in the MenuList. If 
the menu is currently showing on the screen, then its rectangle need not be 
recalculated, since it is stored in the menu bar defproc's data structure. 


If the menu is not currently showing on the screen, the rectangle is calculated. 
If it is the first menu up, the menu drops from the menu bar. If it is a 
hierarchical menu, an attempt is made to line up the top of the hierarchical 
menu with the item that is the "parent" of this submenu. 


Message #10: SaveAlt 


Called By Selector Parameterl Parameter2 Result 
MenuSelect mbVariant none six-byte offset none 
PopUpMenuSelect 


This message is called after message #7 (Save) has been executed and the menu 
defproc has been called to draw the menu items. It currently saves data about 
the menu's scrolling position. A six-byte offset refers to the offset of the 
menu into the menuList data structure. 


Message #11: ResetAlt 


Called By Selector Parameterl Parameter2 Result 
MenuSelect mbVariant none six-byte offset none 
PopUpMenuSelect 


This message is currently used to restore the global variables TopMenuItem 
($AQA) and AtMenuBottom ($AQC) for the menu where the mouse is currently 
located. When a hierarchical menu is drawn, its scrolling information will be in 
the global variables TopMenu Item and AtMenuBottom. For menu scrolling to work 
properly, the scrolling information for the menu where the mouse is currently 
located must be in those global variables. A six-byte offset refers to the 
offset of menu into the menuList data structure. 


Message #12: MenuRgn 
Called By Selector Parameterl Parameter2 Result 
- mbVariant none region handle region handle 


A handle to an empty region is passed in parameter2. The same handle is returned 
as the result, and the region is the menu bar's region. 
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FORMATS OF RESOURCES FOR MENUS 


The resource type for a menu definition procedure is 'MDEF'. The resource data 
is simply the compiled or assembled code of the procedure. 


Icons in menus must be stored in a resource file under the resource type 'ICON' 
with resource IDs from 257 to 511. Strings in resource files have the resource 
type 'STR'; if you use the SetItem procedure to change a menu item's text, you 
should store the alternate text as a string resource. 


The formats of menus and menu bars in resource files are given below. 


Menus in a Resource File 


The resource type for a menu is 'MENU'. The resource data for a menu has the 
format shown below. Once read into memory, this data is stored in a menu record 
(described earlier in the "Menu Records" section). 


Number of bytes Contents 

2 bytes Menu ID 

2 bytes 0; placeholder for menu width 

2 bytes 0; placeholder for menu height 

2 bytes Resource ID of menu definition procedure 
2 bytes 0 (see comment below) 

4 bytes Same as enableFlags field of menu record 
1 byte Length of following title in bytes 

n bytes Characters of menu title 


For each menu item: 


1 byte Length of following text in bytes 

m bytes Text of menu item 

1 byte Icon number, or 0 if no icon 

1 byte Keyboard equivalent, or 0 if none 

1 byte Character marking menu item, or 0 if none 
1 byte Character style of item's text 

1 byte 0, indicating end of menu items 


The four bytes beginning with the resource ID of the menu definition procedure 
serve as a placeholder for the handle to the procedure: When GetMenu is called 
to read the menu from the resource file, it also reads in the menu definition 
procedure if necessary, and replaces these four bytes with a handle to the 
procedure. The resource ID of the standard menu definition procedure is 


CONST textMenuProc = 0; 


The resource data for a nonstandard menu can define menu items in any way 
whatsoever, or not at all, depending on the requirements of its menu definition 
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procedure. If the appearance of the items is basically the same as the standard, 
the resource data might be as shown above, but in fact everything following 

"For each menu item" can have any desired format or can be omitted altogether. 
Similarly, bits 1 to 31 of the enableFlags field may be set and used in any way 
desired by the menu definition procedure; bit 0 applies to the entire menu and 
must reflect whether it's enabled or disabled. 


If your menu definition procedure does use the enableFlags field, menus of that 
type may contain no more than 31 items (1 per available bit); otherwise, the 
number of items they may contain is limited only by the amount of room on the 
screen. 


Note: See the QuickDraw chapter for the exact format of the 
character style byte. 


Menu Bars in a Resource File 


The resource type for the contents of a menu bar is 'MBAR' and the resource data 
has the following format: 


Number of bytes Contents 
2 bytes Number of menus 
For each menu: 


2 bytes Resource ID of menu 
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SUMMARY OF THE MENU MANAGER 


Constants 
CONST 
hMenuCmd = $1B; {itemCmd == $1B ==> hierarchical menu } 
{ attached to this item} 
hierMenu = —-1; {for use as "beforeID" with InsertMenu} 
hPopUpMsg = 3; {pop-up menu placement, asks the defproc to } 
{ calculate the menu rectangle of the pop-up menu} 
mctAllitems = -98; {for use as a "menuItem" with DelMCEntries} 
mctLastIDIndic = -99; {last color table entry has this in ID field} 
dsMBarNFnd = 85; {SysErr code indicating MBDF not found. Used } 
{ by InitProcMenu and InitMenu} 
dsHMenuFindErr = 86; {SysErr code indicating recursive } 


{ hierarchical menus defined. Used by MenuKey. } 
{ Value indicating item has no mark } 
noMark = 0; 


{ Messages to menu definition procedure } 


mDrawMsg = 0; {draw the menu} 
mChooseMsg = 1; {tell which item was chosen and highlight it} 
mSizeMsg = 2; {calculate the menu's dimensions} 


{ Resource ID of standard menu definition procedure } 


textMenuProc = 0; 


Data Types 
TYPE 
MenuHandle = “MenuPtr; 
MenuPtr = “MenuInfo; 
MenuInfo = RECORD 
menuID: INTEGER; {menu ID} 
menuWidth: INTEGER; {menu width in pixels} 
menuHeight : INTEGER; {menu height in pixels} 
menuProc: Handle; {menu definition procedure} 
enableFlags: LONGINT; {tells if menu or items are enabled} 
menuData: Str255 {menu title (and other data) } 
END; 
MCEntryPtr = “MCEntry; 
MCEntry = RECORD 
mctID: INTEGER; {menu ID. ID = 0 is } 


{ the menu bar} 
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mctItem: INTEGER; {menu entry. Item = 0 } 
{ is a title} 
mctRGB1: RGBColor; {usage depends on ID and Item} 
mctRGB2: RGBColor; {usage depends on ID and Item} 
mctRGB3: RGBColor; {usage depends on ID and Item} 
mctRGB4: RGBColor; {usage depends on ID and Item} 
mctReserved: INTEGER; {reserved for internal use} 
END; 
MCTable = ARRAY [0..0] of MCEntry; {The menu entries are } 
{ represented in this array} 
MCTablePtr = “MCTable; 
MCTableHandle = *“MCTablePtr; 
Routines 


Initialization and Allocation 


PROCEDURE InitMenus; 


FUNCTION NewMenu (menuID: INTEGER; menuTitle: Str255) MenuHandle; 

FUNCTION GetMenu (resourceID: INTEGER) MenuHandle; 

PROCEDURE DisposeMenu (theMenu: MenuHandle) ; 

Forming the Menus 

PROCEDURE AppendMenu (theMenu: MenuHandle; data: Str255); 

PROCEDURE AddResMenu (theMenu: MenuHandle; theType: ResType); 

PROCEDURE InsertResMenu (theMenu: MenuHandle; theType: ResType; 
afterItem: INTEGER); 

PROCEDURE InsMenuItem (theMenu: MenuHandle; itemString: Str255; 
afterItem: INTEGER); 

PROCEDURE DelMenuItem (menuItemID: INTEGER); 

Forming the Menu Bar 

PROCEDURE InsertMenu (theMenu: MenuHandle; beforeID: INTEGER); 

PROCEDURE DrawMenuBar; 

PROCEDURE DeleteMenu (menuID: INTEGER); 

PROCEDURE ClearMenuBar; 

FUNCTION GetNewMBar (menuBarID: INTEGER) Handle; 

FUNCTION GetMenuBar : Handle; 

PROCEDURE SetMenuBar (menuList: Handle); 

Choosing From a Menu 

FUNCTION MenuSelect (startPt: Point) LONGINT; 

FUNCTION MenuKey (ch: CHAR) LONGINT; 

PROCEDURE HiliteMenu (menuID: INTEGER); 

Controlling the Appearance of Items 

PROCEDURE SetItem (theMenu: MenuHandle; item: INTEGER; 
itemString: Str255); 
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PROCEDURE GetItem (theMenu: MenuHandle; item: INTEGER; 
VAR itemString: Str255); 
PROCEDURE DisableItem (theMenu: MenuHandle; item: INTEGER); 
PROCEDURE EnableItem (theMenu: MenuHandle; item: INTEGER); 
PROCEDURE CheckItem (theMenu: MenuHandle; item: INTEGER; 
checked: BOOLEAN) ; 
PROCEDURE SetItemMark (theMenu: MenuHandle; item: INTEGER; markChar: CHAR); 
PROCEDURE GetItemMark (theMenu: MenuHandle; item: INTEGER; 
VAR markChar: CHAR); 
PROCEDURE SetItemIcon (theMenu: MenuHandle; item: INTEGER; icon: Byte); 
PROCEDURE GetItemIcon (theMenu: MenuHandle; item: INTEGER; VAR icon: Byte); 
PROCEDURE SetItemStyle (theMenu: MenuHandle; item: INTEGER; chStyle: Style); 
PROCEDURE GetItemStyle (theMenu: MenuHandle; item: INTEGER; 
VAR chStyle: Style); 
Miscellaneous Routines 
PROCEDURE CalcMenuSize (theMenu: MenuHandle) ; 
FUNCTION CountMItems (theMenu: MenuHandle) INTEGER; 
FUNCTION GetMHandle (menuID: INTEGER) MenuHandle; 
PROCEDURE FlashMenuBar (menuID: INTEGER); 
PROCEDURE SetMenuFlash (count: INTEGER); 
New Routines 
PROCEDURE InitProcMenu (mbResID: INTEGER) ; 
PROCEDURE DelMCEntries (menuID, menuIltem: INTEGER); 
FUNCTION GetMCInfo: MCTableHandle; 
PROCEDURE SetMCInfo (menuCTbL: MCTableHandle) ; 
PROCEDURE DispMCInfo (menuCTbL: MCTableHandle) ; 
FUNCTION GetMCEntry (menuID, menuItem: INTEGER): MCEntryPtr; 
FUNCTION MenuChoice: LONGINT; 
PROCEDURE SetMCEntries (numEntries: INTEGER; menuCEntries: MCTablePtr) ; 
PROCEDURE GetItemCmd (theMenu:MenuHandle; item:INTEGER; VAR cmdChar: CHAR); 
PROCEDURE SetItemCmd (theMenu:MenuHandle; item: INTEGER; cmdChar: CHAR); 
FUNCTION PopUpMenuSelect (theMenu: MenuHandle; 


Top, Left, PopupItem: INTEGER; ) LONGINT; 


Meta-Characters for AppendMenu 


Meta-character Usage 


; or Return Separates multiple items 

a Followed by an icon number, adds that icon to the item 

! Followed by a character, marks the item with that character 

< Followed by B, I, U, 0, or S, sets the character style 
of the item 

/ Followed by a character, associates a keyboard equivalent 
with the item 

( Disables the item 


Menu Definition Procedure 
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PROCEDURE MyMenu (message: INTEGER; theMenu: MenuHandle; VAR menuRect: Rect; 


hitPt: Point; VAR whichItem: INTEGER); 


Variables 


MBarHeight 
MenuCInfo 
MenuDisable 


TheMenu 
TopMenuItem 
AtMenuBottom 


Contains menu bar height derived from the size of the system font. 
Contains handle to the menu color information table. 

Contains the menu ID for last menu item chosen, whether or 

not it's disabled. 

Contains the ID of the highlighted menu in the menu bar. 

Contains information on top menu item for menu scrolling. 

Contains information on bottom menu item for menu scrolling. 


Assembly-Language Information 


Constants 


; Value indicating item has no mark 


noMark 


.EQU 0 


; Messages to menu definition procedure 


mDrawMsg 
mChooseMsg 
mSizeMsg 


.EQU 0 ;draw the menu 
-EQU 1 ;tell which item was chosen and highlight it 
.EQU 2 ;calculate the menu's dimensions 


; Resource ID of standard menu definition procedure 


textMenuProc 


.EQU 0 


Menu Record Data Structure 


menuID 
menuWidth 
menuHeight 


Menu ID (word) 
Menu width in pixels (word) 
Menu height in pixels (word) 


menuDefHandle Handle to menu definition procedure 


menuEnable 
menuData 


menuBLkSize 


Enable flags (long) 

Menu title (preceded by length byte) followed by 
data defining the items 

Size in bytes of menu record except menuData field 


Menu Color Information Table Structure 


mctID 

mctItem 
mctRGB1 
mctRGB2 
mctRGB3 
mctRGB4 


EQU $0 
EQU $2 
EQU $4 
EQU $A 
EQU $10 
EQU $16 
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mctReserved 
mctEntrySize 


EQU 
EQU 


$1C 
$1E 


Miscellaneous equates for hierarchical menus 


HMenuCmd 
ScriptMenuCm 


AltMenuCmd1 
AltMenuCmd2 
AltMenuCmd3 


hierMenu 


hPopUpMsg 


Color table 


mctAllitems 
mctLastIDInd 


Special Macr 
Pascal name 


DisposeMenu 
GetItemIcon 
GetItemMark 
GetItemStyle 
GetMenu 
SetItemIcon 
SetItemMark 
SetItemStyle 
SetMenuFlash 


Variables 
MenuList 
MBarEnable 
MenuHook 
MBarHook 


TheMenu 
MenuFlash 


MBarHook rou 


On entry 
On exit 


EQU $1B 
d EQU $1C 
EQU $1D 
EQU $1E 
EQU $1F 
EQU -1 
EQU 3 


search messages 


EQU -98 
ic EQU -99 
o Names 


Macro name 


_DisposMenu 
_GetItmIcon 
_GetItmMark 
_GetItmStyle 
_GetRMenu 
_SetItmIcon 
_SetItmMark 
_SetItmStyle 
_SetMFlash 


sitemCmd == $1B ==> hierarchical menu for this item 
;itemCmd == $1C ==> item to be displayed in 

; script font 

sitemCmd == $1D ==> unused indicator 

; reserved for future Apple use 

sitemCmd == $1E ==> unused indicator 

; reserved for future Apple use 

;itemCmd == $1F ==> unused indicator 


; reserved for future Apple use 


‘InsertMenu(handle, hierMenu) , 


when 


; beforeID ==hierMenu, the handle is 


; inserted in the hierarchical 


menuList 


;pop-up menu placement, asks the defproc to 
; calculate the menu rectangle of the pop-up menu 


;search for all items for the given ID 
;last entry in color table has this in ID field 


Handle to current menu list 
Nonzero if menu bar belongs to a desk accessory (word) 
Address of routine called repeatedly during MenuSelect 
Address of routine called by MenuSelect before 
menu is drawn (see below) 

Menu ID of currently highlighted menu (word) 
Count for duration of menu item blinking (word) 


tine 


stack: 
DO: 


pointer to menu rectangle 
0 to continue MenuSelect 


1 to abort MenuSelect 
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MBarHeight EQU $BAA ;contains menu bar height derived from the 
; size of the system font 


MenuCInfo EQU $0D50 shandle to menu color information table 

MenuDisable EQU $0B54 scontains the menu ID for Last menu item 
; chosen, whether or not it's disabled 

TheMenu EQU $A26 ;contains the ID of the highlighted menu 
; in the menu bar 

TopMenuItem  EQU $A0A ;pixel value of top of scrollable menu 

AtMenuBottom EQU $AOC ;pixel value of bottom of scrollable menu 
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Further Reference: 


Resource Manager 

QuickDraw 

Toolbox Event Manager 

Font Manager 

Window Manager 

Technical Note #172, Parameters for MDEF Message #3 
Technical Note #222, Custom Menu Flashing Bug 


END OF DOCUMENT 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE MENU MANAGER ¢e 65 of 65 


